@shipfox/api-integration-jira 11.0.0 → 12.1.0

package/src/api/client.ts

@@ -1,3 +1,4 @@
+import {jiraWebhookEventNames} from '@shipfox/api-integration-jira-dto';
 import {logger} from '@shipfox/node-opentelemetry';
 import ky, {HTTPError, TimeoutError} from 'ky';
 import {config} from '#config.js';
@@ -5,6 +6,9 @@ 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 = '';
 
 export interface JiraAuthorization {
   accessToken: string;
@@ -24,11 +28,53 @@ export interface JiraIdentity {
   accountId: string;
 }
 
+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>;
   getAccessibleResources(input: {accessToken: string}): Promise<JiraAccessibleResource[]>;
   getMyself(input: {accessToken: string; cloudId: string}): Promise<JiraIdentity>;
+  registerDynamicWebhook(input: {
+    accessToken: string;
+    cloudId: string;
+    url: string;
+  }): Promise<JiraDynamicWebhookRegistration>;
+  deleteDynamicWebhook(input: {
+    accessToken: string;
+    cloudId: string;
+    webhookId: number;
+  }): Promise<void>;
 }
 
 interface JiraTokenResponse {
@@ -49,6 +95,12 @@ interface JiraMyselfResponse {
   accountId?: unknown;
 }
 
+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) {
@@ -115,7 +167,132 @@ export function createJiraApiClient(): JiraApiClient {
       }
       return {accountId: body.accountId};
     },
+
+    async registerDynamicWebhook(input) {
+      const body = await mapJiraError('register-dynamic-webhook', () =>
+        ky
+          .post(`${config.JIRA_API_BASE_URL}/ex/jira/${input.cloudId}/rest/api/3/webhook`, {
+            headers: {authorization: `Bearer ${input.accessToken}`},
+            json: {
+              url: input.url,
+              webhooks: [
+                {
+                  events: JIRA_DYNAMIC_WEBHOOK_EVENTS,
+                  jqlFilter: JIRA_DYNAMIC_WEBHOOK_JQL,
+                },
+              ],
+            },
+            timeout: JIRA_API_TIMEOUT_MS,
+          })
+          .json<JiraDynamicWebhookRegistrationResponse>(),
+      );
+      return parseDynamicWebhookRegistration(body);
+    },
+
+    async deleteDynamicWebhook(input) {
+      await mapJiraError('delete-dynamic-webhook', () =>
+        ky.delete(`${config.JIRA_API_BASE_URL}/ex/jira/${input.cloudId}/rest/api/3/webhook`, {
+          headers: {authorization: `Bearer ${input.accessToken}`},
+          json: {webhookIds: [input.webhookId]},
+          timeout: JIRA_API_TIMEOUT_MS,
+        }),
+      );
+    },
+  };
+}
+
+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 {
+  if (
+    !body ||
+    typeof body !== 'object' ||
+    !Array.isArray(body.webhookRegistrationResult) ||
+    body.webhookRegistrationResult.length !== 1
+  ) {
+    throw malformed('Jira webhook registration response did not contain exactly one result');
+  }
+
+  const result = body.webhookRegistrationResult[0];
+  if (!result || typeof result !== 'object') {
+    throw malformed('Jira webhook registration result was malformed');
+  }
+  const {createdWebhookId, errors} = result as {
+    createdWebhookId?: unknown;
+    errors?: unknown;
   };
+  if (errors !== undefined && (!Array.isArray(errors) || errors.length > 0)) {
+    throw malformed('Jira webhook registration returned errors');
+  }
+  if (
+    typeof createdWebhookId !== 'number' ||
+    !Number.isSafeInteger(createdWebhookId) ||
+    createdWebhookId <= 0
+  ) {
+    throw malformed('Jira webhook registration did not return a created webhook id');
+  }
+  return {webhookId: createdWebhookId};
 }
 
 function parseAuthorization(body: JiraTokenResponse): JiraAuthorization {
@@ -187,6 +364,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) {
@@ -205,6 +391,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/config.test.ts

@@ -2,7 +2,6 @@ const jiraEnvNames = [
   'JIRA_OAUTH_CLIENT_ID',
   'JIRA_OAUTH_CLIENT_SECRET',
   'JIRA_OAUTH_REDIRECT_URL',
-  'JIRA_WEBHOOK_SIGNING_SECRET',
   'JIRA_WEBHOOK_BASE_URL',
 ] as const;
 

package/src/config.ts

@@ -5,14 +5,11 @@ export const config = createConfig({
     desc: 'OAuth client ID of the Jira app, used to start and complete the Jira connect flow. Required.',
   }),
   JIRA_OAUTH_CLIENT_SECRET: str({
-    desc: 'OAuth client secret of the Jira app, used to exchange authorization codes for access and refresh tokens. Required.',
+    desc: 'OAuth client secret of the Jira app, used for authorization-code exchange and inbound webhook JWT verification. Required.',
   }),
   JIRA_OAUTH_REDIRECT_URL: url({
     desc: 'Public client callback URL Jira redirects to after OAuth authorization, such as https://shipfox.example.com/integrations/jira/callback. Required.',
   }),
-  JIRA_WEBHOOK_SIGNING_SECRET: str({
-    desc: 'Secret used to verify incoming Jira webhooks. It must match the webhook signing secret configured for the Jira app. Required.',
-  }),
   JIRA_WEBHOOK_BASE_URL: url({
     desc: 'Public base URL Jira sends webhooks to. Its origin must be added to the Jira app webhook allowlist. Required.',
   }),

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