@shipfox/api-integration-jira 12.0.0 → 12.1.0

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