@shipfox/api-integration-jira 12.0.0 → 12.1.1

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.1",
   "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,24 @@ 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(),
+  warn: vi.fn(),
+}));
+
+vi.mock('@shipfox/node-opentelemetry', () => ({
+  logger: () => ({
+    warn: mocks.warn,
+  }),
+}));
 
 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 +31,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 +63,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 +87,8 @@ describe('Jira dynamic webhook API', () => {
   beforeEach(() => {
     mocks.delete.mockReset();
     mocks.post.mockReset();
+    mocks.request.mockReset();
+    mocks.warn.mockReset();
   });
 
   it('registers the six curated events with the access token', async () => {
@@ -114,6 +145,165 @@ describe('Jira dynamic webhook API', () => {
     ).rejects.toMatchObject({reason: 'malformed-provider-response'});
   });
 
+  it('logs provider validation errors before rejecting registration', async () => {
+    mocks.post.mockReturnValue(
+      resolves({
+        webhookRegistrationResult: [
+          {createdWebhookId: 123, errors: ['Webhook URL is not approved', 'Invalid JQL filter']},
+        ],
+      }),
+    );
+    const {createJiraApiClient} = await import('./client.js');
+
+    await expect(
+      createJiraApiClient().registerDynamicWebhook({
+        accessToken: 'access-token',
+        cloudId: 'cloud-1',
+        url: 'https://shipfox.example.com/webhooks/integrations/jira/connection-1',
+      }),
+    ).rejects.toMatchObject({reason: 'malformed-provider-response'});
+
+    expect(mocks.warn).toHaveBeenCalledTimes(1);
+    expect(mocks.warn).toHaveBeenCalledWith(
+      {
+        operation: 'register-dynamic-webhook',
+        providerErrors: ['Webhook URL is not approved', 'Invalid JQL filter'],
+        providerErrorCount: 2,
+      },
+      'Jira dynamic webhook registration rejected',
+    );
+  });
+
+  it('limits logged provider errors to five values', async () => {
+    mocks.post.mockReturnValue(
+      resolves({
+        webhookRegistrationResult: [
+          {
+            errors: ['one', 'two', 'three', 'four', 'five', 'six'],
+          },
+        ],
+      }),
+    );
+    const {createJiraApiClient} = await import('./client.js');
+
+    await expect(
+      createJiraApiClient().registerDynamicWebhook({
+        accessToken: 'access-token',
+        cloudId: 'cloud-1',
+        url: 'https://shipfox.example.com/webhooks/integrations/jira/connection-1',
+      }),
+    ).rejects.toMatchObject({reason: 'malformed-provider-response'});
+
+    expect(mocks.warn).toHaveBeenCalledWith(
+      {
+        operation: 'register-dynamic-webhook',
+        providerErrors: ['one', 'two', 'three', 'four', 'five'],
+        providerErrorCount: 6,
+      },
+      'Jira dynamic webhook registration rejected',
+    );
+  });
+
+  it('limits each logged provider error to 500 characters', async () => {
+    const longError = 'x'.repeat(501);
+    mocks.post.mockReturnValue(resolves({webhookRegistrationResult: [{errors: [longError]}]}));
+    const {createJiraApiClient} = await import('./client.js');
+
+    await expect(
+      createJiraApiClient().registerDynamicWebhook({
+        accessToken: 'access-token',
+        cloudId: 'cloud-1',
+        url: 'https://shipfox.example.com/webhooks/integrations/jira/connection-1',
+      }),
+    ).rejects.toMatchObject({reason: 'malformed-provider-response'});
+
+    expect(mocks.warn).toHaveBeenCalledWith(
+      {
+        operation: 'register-dynamic-webhook',
+        providerErrors: ['x'.repeat(500)],
+        providerErrorCount: 1,
+      },
+      'Jira dynamic webhook registration rejected',
+    );
+  });
+
+  it('omits non-string provider errors from the warning', async () => {
+    mocks.post.mockReturnValue(
+      resolves({
+        webhookRegistrationResult: [
+          {errors: ['valid message', 42, null, {message: 'raw response'}, true]},
+        ],
+      }),
+    );
+    const {createJiraApiClient} = await import('./client.js');
+
+    await expect(
+      createJiraApiClient().registerDynamicWebhook({
+        accessToken: 'access-token',
+        cloudId: 'cloud-1',
+        url: 'https://shipfox.example.com/webhooks/integrations/jira/connection-1',
+      }),
+    ).rejects.toMatchObject({reason: 'malformed-provider-response'});
+
+    expect(mocks.warn).toHaveBeenCalledWith(
+      {
+        operation: 'register-dynamic-webhook',
+        providerErrors: ['valid message'],
+        providerErrorCount: 5,
+      },
+      'Jira dynamic webhook registration rejected',
+    );
+  });
+
+  it('accepts an empty provider errors array without logging a rejection', async () => {
+    mocks.post.mockReturnValue(
+      resolves({webhookRegistrationResult: [{createdWebhookId: 123, errors: []}]}),
+    );
+    const {createJiraApiClient} = await import('./client.js');
+
+    await expect(
+      createJiraApiClient().registerDynamicWebhook({
+        accessToken: 'access-token',
+        cloudId: 'cloud-1',
+        url: 'https://shipfox.example.com/webhooks/integrations/jira/connection-1',
+      }),
+    ).resolves.toEqual({webhookId: 123});
+    expect(mocks.warn).not.toHaveBeenCalled();
+  });
+
+  it('rejects a non-array provider errors value without logging it', async () => {
+    mocks.post.mockReturnValue(
+      resolves({
+        webhookRegistrationResult: [{createdWebhookId: 123, errors: {message: 'do not log me'}}],
+      }),
+    );
+    const {createJiraApiClient} = await import('./client.js');
+
+    await expect(
+      createJiraApiClient().registerDynamicWebhook({
+        accessToken: 'access-token',
+        cloudId: 'cloud-1',
+        url: 'https://shipfox.example.com/webhooks/integrations/jira/connection-1',
+      }),
+    ).rejects.toMatchObject({reason: 'malformed-provider-response'});
+    expect(mocks.warn).not.toHaveBeenCalled();
+  });
+
+  it('keeps the malformed provider response reason for a Jira rejection', async () => {
+    mocks.post.mockReturnValue(
+      resolves({webhookRegistrationResult: [{errors: ['Provider rejected the webhook']}]}),
+    );
+    const {createJiraApiClient} = await import('./client.js');
+
+    await expect(
+      createJiraApiClient().registerDynamicWebhook({
+        accessToken: 'access-token',
+        cloudId: 'cloud-1',
+        url: 'https://shipfox.example.com/webhooks/integrations/jira/connection-1',
+      }),
+    ).rejects.toMatchObject({reason: 'malformed-provider-response'});
+  });
+
   it('deletes a dynamic webhook by id', async () => {
     mocks.delete.mockResolvedValue(undefined);
     const {createJiraApiClient} = await import('./client.js');
@@ -133,3 +323,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'});
+  });
+});