@shipfox/api-integration-jira 12.0.0 → 12.1.0

package/drizzle/0001_jira-token-refresh-state.sql

@@ -0,0 +1,12 @@
+ALTER TABLE "integrations_jira_installations" ADD COLUMN "refresh_token_last_used_at" timestamp with time zone;--> statement-breakpoint
+ALTER TABLE "integrations_jira_installations" ADD COLUMN "refresh_token_last_attempted_at" timestamp with time zone;--> statement-breakpoint
+UPDATE "integrations_jira_installations"
+SET
+  "refresh_token_last_used_at" = "created_at",
+  "refresh_token_last_attempted_at" = "created_at";--> statement-breakpoint
+ALTER TABLE "integrations_jira_installations" ALTER COLUMN "refresh_token_last_used_at" SET DEFAULT now();--> statement-breakpoint
+ALTER TABLE "integrations_jira_installations" ALTER COLUMN "refresh_token_last_used_at" SET NOT NULL;--> statement-breakpoint
+ALTER TABLE "integrations_jira_installations" ALTER COLUMN "refresh_token_last_attempted_at" SET DEFAULT now();--> statement-breakpoint
+ALTER TABLE "integrations_jira_installations" ALTER COLUMN "refresh_token_last_attempted_at" SET NOT NULL;--> statement-breakpoint
+CREATE INDEX "integrations_jira_installations_token_refresh_due_idx" ON "integrations_jira_installations" USING btree ("status","refresh_token_last_used_at");--> statement-breakpoint
+CREATE INDEX "integrations_jira_installations_token_refresh_attempt_idx" ON "integrations_jira_installations" USING btree ("status","refresh_token_last_attempted_at");

package/drizzle/meta/0001_snapshot.json

@@ -0,0 +1,245 @@
+{
+  "id": "9ddf6898-1a59-4d58-a3c1-7a8fc1587c00",
+  "prevId": "5903a3ad-8572-4443-9fb4-8eb0298fab14",
+  "version": "7",
+  "dialect": "postgresql",
+  "tables": {
+    "public.integrations_jira_installations": {
+      "name": "integrations_jira_installations",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "uuid",
+          "primaryKey": true,
+          "notNull": true,
+          "default": "uuidv7()"
+        },
+        "connection_id": {
+          "name": "connection_id",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "cloud_id": {
+          "name": "cloud_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "site_url": {
+          "name": "site_url",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "site_name": {
+          "name": "site_name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "authorizing_account_id": {
+          "name": "authorizing_account_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "scopes": {
+          "name": "scopes",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "webhook_ids": {
+          "name": "webhook_ids",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'[]'::jsonb"
+        },
+        "webhook_expires_at": {
+          "name": "webhook_expires_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "status": {
+          "name": "status",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "token_expires_at": {
+          "name": "token_expires_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "refresh_token_last_used_at": {
+          "name": "refresh_token_last_used_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "refresh_token_last_attempted_at": {
+          "name": "refresh_token_last_attempted_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "integrations_jira_installations_connection_unique": {
+          "name": "integrations_jira_installations_connection_unique",
+          "columns": [
+            {
+              "expression": "connection_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "integrations_jira_installations_cloud_id_unique": {
+          "name": "integrations_jira_installations_cloud_id_unique",
+          "columns": [
+            {
+              "expression": "cloud_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "integrations_jira_installations_token_refresh_due_idx": {
+          "name": "integrations_jira_installations_token_refresh_due_idx",
+          "columns": [
+            {
+              "expression": "status",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "refresh_token_last_used_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "integrations_jira_installations_token_refresh_attempt_idx": {
+          "name": "integrations_jira_installations_token_refresh_attempt_idx",
+          "columns": [
+            {
+              "expression": "status",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "refresh_token_last_attempted_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.integrations_jira_pending_selections": {
+      "name": "integrations_jira_pending_selections",
+      "schema": "",
+      "columns": {
+        "state_hash": {
+          "name": "state_hash",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "workspace_id": {
+          "name": "workspace_id",
+          "type": "uuid",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "expires_at": {
+          "name": "expires_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "sites": {
+          "name": "sites",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    }
+  },
+  "enums": {},
+  "schemas": {},
+  "sequences": {},
+  "roles": {},
+  "policies": {},
+  "views": {},
+  "_meta": {
+    "columns": {},
+    "schemas": {},
+    "tables": {}
+  }
+}

package/drizzle/meta/_journal.json

@@ -8,6 +8,13 @@
       "when": 1784385935754,
       "tag": "0000_whole_master_chief",
       "breakpoints": true
+    },
+    {
+      "idx": 1,
+      "version": "7",
+      "when": 1785832279528,
+      "tag": "0001_jira-token-refresh-state",
+      "breakpoints": true
     }
   ]
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shipfox/api-integration-jira",
   "license": "MIT",
-  "version": "12.0.0",
+  "version": "12.1.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ShipfoxHQ/shipfox.git",
@@ -15,21 +15,28 @@
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
+    },
+    "./agent-tools": {
+      "types": "./dist/core/agent-tools.d.ts",
+      "default": "./dist/core/agent-tools.js"
     }
   },
   "dependencies": {
+    "@temporalio/activity": "1.18.1",
+    "@temporalio/workflow": "1.18.1",
     "drizzle-orm": "^0.45.2",
     "ky": "^2.0.0",
     "zod": "^4.4.3",
     "@shipfox/api-auth-context": "12.0.0",
     "@shipfox/api-integration-spi": "1.0.0",
+    "@shipfox/api-integration-jira-dto": "12.0.0",
     "@shipfox/config": "1.2.4",
     "@shipfox/node-drizzle": "0.3.5",
-    "@shipfox/api-integration-jira-dto": "12.0.0",
     "@shipfox/node-fastify": "0.4.1",
+    "@shipfox/node-jwt": "0.4.0",
+    "@shipfox/node-module": "1.0.5",
     "@shipfox/node-opentelemetry": "0.6.3",
-    "@shipfox/node-postgres": "0.5.0",
-    "@shipfox/node-jwt": "0.4.0"
+    "@shipfox/node-postgres": "0.5.0"
   },
   "imports": {
     "#*": "./dist/*"
@@ -43,7 +50,7 @@
     }
   },
   "scripts": {
-    "build": "shipfox-swc",
+    "build": "shipfox-swc && shipfox-temporal-bundle dist/temporal/workflows/index.js",
     "check": "shipfox-biome-check",
     "check:fix": "shipfox-biome-check --write",
     "depcruise": "shipfox-depcruise",

package/src/api/client.test.ts

@@ -2,11 +2,13 @@ import {HTTPError} from 'ky';
 import type {JiraIntegrationProviderError} from '#core/errors.js';
 import {mapJiraError} from './client.js';
 
-const mocks = vi.hoisted(() => ({delete: vi.fn(), post: vi.fn()}));
+const mocks = vi.hoisted(() => ({delete: vi.fn(), post: vi.fn(), request: vi.fn()}));
 
 vi.mock('ky', () => {
   class MockHTTPError extends Error {
-    constructor(public response: {status: number; statusText?: string; headers: Headers}) {
+    data?: unknown;
+
+    constructor(public response: Response) {
       super('http');
       this.name = 'HTTPError';
     }
@@ -18,21 +20,23 @@ vi.mock('ky', () => {
     }
   }
   return {
-    default: {delete: mocks.delete, post: mocks.post},
+    default: Object.assign(mocks.request, {delete: mocks.delete, post: mocks.post}),
     HTTPError: MockHTTPError,
     TimeoutError: MockTimeoutError,
   };
 });
 
-function rejectedRequest(status: number): () => Promise<never> {
-  return () =>
-    Promise.reject(
-      new HTTPError(
-        new Response(null, {status}),
-        new Request('https://jira.example.test'),
-        {} as never,
-      ),
-    );
+function rejectedRequest(status: number, body?: {error: string}): () => Promise<never> {
+  return async () => {
+    const response = new Response(body ? JSON.stringify(body) : null, {
+      status,
+      ...(body ? {headers: {'content-type': 'application/json'}} : {}),
+    });
+    const error = new HTTPError(response, new Request('https://jira.example.test'), {} as never);
+    await response.text();
+    error.data = body;
+    throw error;
+  };
 }
 
 describe('mapJiraError', () => {
@@ -48,6 +52,20 @@ describe('mapJiraError', () => {
       reason,
     } satisfies Partial<JiraIntegrationProviderError>);
   });
+
+  it.each([
+    ['invalid_grant', 'access-denied'],
+    ['unauthorized_client', 'access-denied'],
+    ['invalid_request', 'malformed-provider-response'],
+    [undefined, 'malformed-provider-response'],
+  ] as const)('maps refresh HTTP 400 with OAuth error %s to %s', async (errorCode, reason) => {
+    const result = mapJiraError(
+      'refresh-access-token',
+      rejectedRequest(400, errorCode ? {error: errorCode} : undefined),
+    );
+
+    await expect(result).rejects.toMatchObject({reason});
+  });
 });
 
 function resolves(data: unknown) {
@@ -58,6 +76,7 @@ describe('Jira dynamic webhook API', () => {
   beforeEach(() => {
     mocks.delete.mockReset();
     mocks.post.mockReset();
+    mocks.request.mockReset();
   });
 
   it('registers the six curated events with the access token', async () => {
@@ -133,3 +152,105 @@ describe('Jira dynamic webhook API', () => {
     );
   });
 });
+
+describe('Jira agent-tools REST API', () => {
+  beforeEach(() => {
+    mocks.request.mockReset();
+  });
+
+  it('sends a REST v3 request and parses a JSON response', async () => {
+    mocks.request.mockResolvedValue(
+      new Response(JSON.stringify({id: '1004', key: 'ENG-1004'}), {status: 200}),
+    );
+    const {createJiraAgentToolsClient} = await import('./client.js');
+
+    const result = await createJiraAgentToolsClient().request({
+      accessToken: 'access-token',
+      cloudId: 'cloud-1',
+      method: 'GET',
+      path: '/issue/ENG-1004',
+      query: {fields: ['summary', 'description'], updateHistory: false},
+      operation: 'get_issue',
+    });
+
+    expect(result).toEqual({status: 200, body: {id: '1004', key: 'ENG-1004'}});
+    const [url, options] = mocks.request.mock.calls[0] as [
+      string,
+      {headers: Record<string, string>; searchParams: URLSearchParams},
+    ];
+    expect(url).toBe('http://127.0.0.1:0/ex/jira/cloud-1/rest/api/3/issue/ENG-1004');
+    expect(options.headers).toEqual({authorization: 'Bearer access-token'});
+    expect([...options.searchParams.entries()]).toEqual([
+      ['fields', 'summary'],
+      ['fields', 'description'],
+      ['updateHistory', 'false'],
+    ]);
+  });
+
+  it('maps HTTP 429 Retry-After responses to a rate-limited provider error', async () => {
+    mocks.request.mockRejectedValue(
+      new HTTPError(
+        new Response(null, {status: 429, headers: {'retry-after': '19'}}),
+        new Request('https://jira.example.test'),
+        {} as never,
+      ),
+    );
+    const {createJiraAgentToolsClient} = await import('./client.js');
+
+    await expect(
+      createJiraAgentToolsClient().request({
+        accessToken: 'access-token',
+        cloudId: 'cloud-1',
+        method: 'GET',
+        path: '/issue/ENG-1004',
+        operation: 'get_issue',
+      }),
+    ).rejects.toMatchObject({reason: 'rate-limited', retryAfterSeconds: 19});
+  });
+
+  it('preserves Jira validation details from HTTP 400 responses', async () => {
+    mocks.request.mockRejectedValue(
+      new HTTPError(
+        new Response(JSON.stringify({errorMessages: ['The JQL query is invalid']}), {status: 400}),
+        new Request('https://jira.example.test'),
+        {} as never,
+      ),
+    );
+    const {createJiraAgentToolsClient} = await import('./client.js');
+
+    await expect(
+      createJiraAgentToolsClient().request({
+        accessToken: 'access-token',
+        cloudId: 'cloud-1',
+        method: 'POST',
+        path: '/search/jql',
+        body: {jql: 'not valid'},
+        operation: 'search_issues',
+      }),
+    ).resolves.toEqual({
+      status: 400,
+      body: {errorMessages: ['The JQL query is invalid']},
+    });
+  });
+
+  it('maps HTTP 401 responses to an access-denied provider error', async () => {
+    mocks.request.mockRejectedValue(
+      new HTTPError(
+        new Response(null, {status: 401}),
+        new Request('https://jira.example.test'),
+        {} as never,
+      ),
+    );
+    const {createJiraAgentToolsClient} = await import('./client.js');
+
+    await expect(
+      createJiraAgentToolsClient().request({
+        accessToken: 'access-token',
+        cloudId: 'cloud-1',
+        method: 'GET',
+        path: '/issue/ENG-1004',
+        operation: 'get_issue',
+      }),
+    ).rejects.toMatchObject({reason: 'access-denied'});
+  });
+});

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 {
@@ -272,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) {
@@ -290,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;