@shipfox/api-integration-jira 11.0.0 → 12.1.0

package/src/temporal/activities/refresh-jira-tokens.test.ts

@@ -0,0 +1,156 @@
+import type {JiraInstallation} from '#db/installations.js';
+import {JIRA_REFRESH_TOKEN_PROACTIVE_REFRESH_AFTER_MS} from '#temporal/constants.js';
+import {createJiraMaintenanceActivities} from './index.js';
+
+function installation(connectionId: string): JiraInstallation {
+  const now = new Date('2026-01-01T00:00:00.000Z');
+  return {
+    id: crypto.randomUUID(),
+    connectionId,
+    cloudId: crypto.randomUUID(),
+    siteUrl: 'https://acme.atlassian.net',
+    siteName: 'Acme',
+    authorizingAccountId: crypto.randomUUID(),
+    scopes: ['offline_access'],
+    webhookIds: [],
+    webhookExpiresAt: null,
+    status: 'installed',
+    tokenExpiresAt: now,
+    refreshTokenLastUsedAt: now,
+    refreshTokenLastAttemptedAt: now,
+    createdAt: now,
+    updatedAt: now,
+  };
+}
+
+describe('Jira proactive token refresh activity', () => {
+  it('force-refreshes due active connections and skips inactive ones', async () => {
+    const activeConnectionId = crypto.randomUUID();
+    const inactiveConnectionId = crypto.randomUUID();
+    const failedConnectionId = crypto.randomUUID();
+    const installations = [
+      installation(activeConnectionId),
+      installation(inactiveConnectionId),
+      installation(failedConnectionId),
+    ];
+    const listInstallations = vi.fn().mockResolvedValue(installations);
+    const resolveConnection = vi
+      .fn()
+      .mockImplementation(async (connectionId: string) =>
+        connectionId === activeConnectionId
+          ? {lifecycleStatus: 'active'}
+          : connectionId === failedConnectionId
+            ? {lifecycleStatus: 'active'}
+            : {lifecycleStatus: 'error'},
+      );
+    const getAccessToken = vi.fn().mockImplementation(({connectionId}: {connectionId: string}) => {
+      if (connectionId === failedConnectionId) throw new Error('refresh failed');
+      return 'fresh-access-token';
+    });
+    const heartbeat = vi.fn();
+    const markAttempted = vi.fn().mockResolvedValue(undefined);
+    const now = new Date('2026-08-04T00:00:00.000Z');
+    const activities = createJiraMaintenanceActivities({
+      tokenStore: {getAccessToken},
+      resolveConnection,
+      listInstallations,
+      markAttempted,
+      now: () => now,
+      heartbeat,
+    });
+
+    const result = await activities.refreshJiraTokensActivity();
+
+    expect(listInstallations).toHaveBeenCalledWith({
+      before: new Date(now.getTime() - JIRA_REFRESH_TOKEN_PROACTIVE_REFRESH_AFTER_MS),
+      limit: 20,
+    });
+    expect(getAccessToken).toHaveBeenCalledWith({
+      connectionId: activeConnectionId,
+      forceRefresh: true,
+    });
+    expect(getAccessToken).toHaveBeenCalledTimes(2);
+    expect(heartbeat).toHaveBeenCalledTimes(6);
+    expect(markAttempted).toHaveBeenCalledTimes(3);
+    expect(result).toEqual({refreshed: 1, skipped: 1, failed: 1});
+  });
+
+  it('heartbeats while a token refresh is in flight', async () => {
+    vi.useFakeTimers();
+    try {
+      const connectionId = crypto.randomUUID();
+      let resolveToken!: (value: string | PromiseLike<string>) => void;
+      const getAccessToken = vi.fn(
+        () =>
+          new Promise<string>((resolve) => {
+            resolveToken = resolve;
+          }),
+      );
+      const heartbeat = vi.fn();
+      const activities = createJiraMaintenanceActivities({
+        tokenStore: {getAccessToken},
+        resolveConnection: vi.fn().mockResolvedValue({lifecycleStatus: 'active'}),
+        listInstallations: vi.fn().mockResolvedValue([installation(connectionId)]),
+        markAttempted: vi.fn().mockResolvedValue(undefined),
+        heartbeat,
+      });
+
+      const result = activities.refreshJiraTokensActivity();
+      await vi.waitFor(() => expect(getAccessToken).toHaveBeenCalledOnce());
+      const heartbeatCountBeforeRefresh = heartbeat.mock.calls.length;
+
+      await vi.advanceTimersByTimeAsync(30_000);
+
+      expect(heartbeat.mock.calls.length).toBeGreaterThan(heartbeatCountBeforeRefresh);
+      resolveToken('fresh-access-token');
+      await expect(result).resolves.toEqual({refreshed: 1, skipped: 0, failed: 0});
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it('counts an attempt failure and continues with the next installation', async () => {
+    const failedConnectionId = crypto.randomUUID();
+    const activeConnectionId = crypto.randomUUID();
+    const installations = [installation(failedConnectionId), installation(activeConnectionId)];
+    const activities = createJiraMaintenanceActivities({
+      tokenStore: {getAccessToken: vi.fn().mockResolvedValue('fresh-access-token')},
+      resolveConnection: vi.fn().mockResolvedValue({lifecycleStatus: 'active'}),
+      listInstallations: vi.fn().mockResolvedValue(installations),
+      markAttempted: vi
+        .fn()
+        .mockRejectedValueOnce(new Error('attempt write failed'))
+        .mockResolvedValue(undefined),
+      heartbeat: vi.fn(),
+    });
+
+    const result = await activities.refreshJiraTokensActivity();
+
+    expect(result).toEqual({refreshed: 1, skipped: 0, failed: 1});
+  });
+
+  it('counts a connection lookup failure and continues with the next installation', async () => {
+    const failedConnectionId = crypto.randomUUID();
+    const activeConnectionId = crypto.randomUUID();
+    const getAccessToken = vi.fn().mockResolvedValue('fresh-access-token');
+    const activities = createJiraMaintenanceActivities({
+      tokenStore: {getAccessToken},
+      resolveConnection: vi
+        .fn()
+        .mockRejectedValueOnce(new Error('connection lookup failed'))
+        .mockResolvedValue({lifecycleStatus: 'active'}),
+      listInstallations: vi
+        .fn()
+        .mockResolvedValue([installation(failedConnectionId), installation(activeConnectionId)]),
+      markAttempted: vi.fn().mockResolvedValue(undefined),
+    });
+
+    const result = await activities.refreshJiraTokensActivity();
+
+    expect(getAccessToken).toHaveBeenCalledWith({
+      connectionId: activeConnectionId,
+      forceRefresh: true,
+    });
+    expect(result).toEqual({refreshed: 1, skipped: 0, failed: 1});
+  });
+});

package/src/temporal/activities/refresh-jira-tokens.ts

@@ -0,0 +1,88 @@
+import type {IntegrationConnection} from '@shipfox/api-integration-spi';
+import {logger} from '@shipfox/node-opentelemetry';
+import type {JiraTokenStore} from '#core/tokens.js';
+import {
+  type JiraInstallation,
+  listJiraInstallationsDueForTokenRefresh,
+  markJiraInstallationTokenRefreshAttempt,
+} from '#db/installations.js';
+import {
+  JIRA_REFRESH_TOKEN_PROACTIVE_REFRESH_AFTER_MS,
+  JIRA_REFRESH_TOKEN_SWEEP_BATCH_SIZE,
+} from '#temporal/constants.js';
+
+const JIRA_REFRESH_TOKEN_HEARTBEAT_INTERVAL_MS = 15_000;
+
+export interface JiraTokenRefreshActivityResult {
+  refreshed: number;
+  skipped: number;
+  failed: number;
+}
+
+export interface CreateJiraMaintenanceActivitiesOptions {
+  tokenStore: Pick<JiraTokenStore, 'getAccessToken'>;
+  resolveConnection(
+    connectionId: string,
+  ): Promise<Pick<IntegrationConnection, 'lifecycleStatus'> | undefined>;
+  listInstallations?: typeof listJiraInstallationsDueForTokenRefresh | undefined;
+  markAttempted?: typeof markJiraInstallationTokenRefreshAttempt | undefined;
+  now?: (() => Date) | undefined;
+  heartbeat?: (() => void) | undefined;
+}
+
+export function createJiraMaintenanceActivities(options: CreateJiraMaintenanceActivitiesOptions) {
+  const listInstallations = options.listInstallations ?? listJiraInstallationsDueForTokenRefresh;
+  const markAttempted = options.markAttempted ?? markJiraInstallationTokenRefreshAttempt;
+  const now = options.now ?? (() => new Date());
+  const heartbeat = options.heartbeat ?? (() => undefined);
+
+  return {
+    async refreshJiraTokensActivity(): Promise<JiraTokenRefreshActivityResult> {
+      const before = new Date(now().getTime() - JIRA_REFRESH_TOKEN_PROACTIVE_REFRESH_AFTER_MS);
+      const installations = await listInstallations({
+        before,
+        limit: JIRA_REFRESH_TOKEN_SWEEP_BATCH_SIZE,
+      });
+      let refreshed = 0;
+      let skipped = 0;
+      let failed = 0;
+
+      for (const installation of installations) {
+        const heartbeatInterval = setInterval(heartbeat, JIRA_REFRESH_TOKEN_HEARTBEAT_INTERVAL_MS);
+        try {
+          heartbeat();
+          await markAttempted(installation.connectionId);
+          const connection = await options.resolveConnection(installation.connectionId);
+          if (connection?.lifecycleStatus !== 'active') {
+            skipped += 1;
+            continue;
+          }
+
+          await options.tokenStore.getAccessToken({
+            connectionId: installation.connectionId,
+            forceRefresh: true,
+          });
+          refreshed += 1;
+        } catch (error) {
+          failed += 1;
+          logRefreshFailure(installation, error);
+        } finally {
+          clearInterval(heartbeatInterval);
+          heartbeat();
+        }
+      }
+
+      return {refreshed, skipped, failed};
+    },
+  };
+}
+
+function logRefreshFailure(installation: JiraInstallation, error: unknown): void {
+  logger().warn(
+    {
+      connectionId: installation.connectionId,
+      err: error,
+    },
+    'Jira proactive token refresh failed',
+  );
+}

package/src/temporal/constants.ts

@@ -0,0 +1,8 @@
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+
+export const JIRA_REFRESH_TOKEN_IDLE_WINDOW_MS = 90 * MS_PER_DAY;
+export const JIRA_REFRESH_TOKEN_REFRESH_LEAD_TIME_MS = 14 * MS_PER_DAY;
+export const JIRA_REFRESH_TOKEN_PROACTIVE_REFRESH_AFTER_MS =
+  JIRA_REFRESH_TOKEN_IDLE_WINDOW_MS - JIRA_REFRESH_TOKEN_REFRESH_LEAD_TIME_MS;
+export const JIRA_REFRESH_TOKEN_SWEEP_BATCH_SIZE = 20;
+export const JIRA_MAINTENANCE_TASK_QUEUE = 'integrations-jira-maintenance';

package/src/temporal/worker.ts

@@ -0,0 +1,39 @@
+import {dirname, resolve} from 'node:path';
+import {fileURLToPath} from 'node:url';
+import type {IntegrationConnection} from '@shipfox/api-integration-spi';
+import type {ModuleWorker} from '@shipfox/node-module';
+import {Context} from '@temporalio/activity';
+import type {JiraTokenStore} from '#core/tokens.js';
+import {createJiraMaintenanceActivities} from '#temporal/activities/index.js';
+import {JIRA_MAINTENANCE_TASK_QUEUE} from '#temporal/constants.js';
+
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '../..');
+const workflowsPath = resolve(packageRoot, 'dist/temporal/workflows/index.js');
+
+export interface CreateJiraMaintenanceWorkerOptions {
+  tokenStore: Pick<JiraTokenStore, 'getAccessToken'>;
+  resolveConnection(
+    connectionId: string,
+  ): Promise<Pick<IntegrationConnection, 'lifecycleStatus'> | undefined>;
+}
+
+export function createJiraMaintenanceWorker(
+  options: CreateJiraMaintenanceWorkerOptions,
+): ModuleWorker {
+  return {
+    taskQueue: JIRA_MAINTENANCE_TASK_QUEUE,
+    workflowsPath,
+    activities: () =>
+      createJiraMaintenanceActivities({
+        ...options,
+        heartbeat: () => Context.current().heartbeat(),
+      }),
+    workflows: [
+      {
+        name: 'refreshJiraTokensCron',
+        id: 'jira-refresh-tokens',
+        cronSchedule: '0 */6 * * *',
+      },
+    ],
+  };
+}

package/src/temporal/workflows/index.ts

@@ -0,0 +1 @@
+export {refreshJiraTokensCron} from './refresh-jira-tokens-cron.js';

package/src/temporal/workflows/refresh-jira-tokens-cron.ts

@@ -0,0 +1,19 @@
+import {log, proxyActivities} from '@temporalio/workflow';
+import type {createJiraMaintenanceActivities} from '../activities/index.js';
+
+const {refreshJiraTokensActivity} = proxyActivities<
+  ReturnType<typeof createJiraMaintenanceActivities>
+>({
+  startToCloseTimeout: '5 minutes',
+  heartbeatTimeout: '1 minute',
+  // A later cron run is the retry mechanism. Retrying this serial sweep in-place
+  // could overlap a still-running attempt after a timeout.
+  retry: {maximumAttempts: 1},
+});
+
+export async function refreshJiraTokensCron(): Promise<void> {
+  const result = await refreshJiraTokensActivity();
+  if (result.refreshed > 0 || result.failed > 0 || result.skipped > 0) {
+    log.info('Completed Jira proactive token refresh', {...result});
+  }
+}

package/test/env.ts

@@ -8,7 +8,6 @@ process.env.TZ = 'UTC';
 process.env.JIRA_OAUTH_CLIENT_ID = 'test-client-id';
 process.env.JIRA_OAUTH_CLIENT_SECRET = 'test-client-secret';
 process.env.JIRA_OAUTH_REDIRECT_URL = 'https://shipfox.example.com/integrations/jira/callback';
-process.env.JIRA_WEBHOOK_SIGNING_SECRET = 'test-signing-secret';
 process.env.JIRA_WEBHOOK_BASE_URL = 'https://shipfox.example.com';
 process.env.JIRA_API_BASE_URL = 'http://127.0.0.1:0';
 process.env.JIRA_AUTH_BASE_URL = 'http://127.0.0.1:0';

package/test/factories/jira-installation.ts

@@ -14,6 +14,8 @@ export const jiraInstallationFactory = Factory.define<JiraInstallation>(({sequen
       webhookExpiresAt: installation.webhookExpiresAt,
       status: installation.status,
       tokenExpiresAt: installation.tokenExpiresAt,
+      refreshTokenLastUsedAt: installation.refreshTokenLastUsedAt,
+      refreshTokenLastAttemptedAt: installation.refreshTokenLastAttemptedAt,
     }),
   );
 
@@ -29,6 +31,8 @@ export const jiraInstallationFactory = Factory.define<JiraInstallation>(({sequen
     webhookExpiresAt: null,
     status: 'installed',
     tokenExpiresAt: null,
+    refreshTokenLastUsedAt: new Date(),
+    refreshTokenLastAttemptedAt: new Date(),
     createdAt: new Date(),
     updatedAt: new Date(),
   };