@shipfox/api-integration-jira 11.0.0 → 12.1.0

package/src/core/webhook-registration.ts

@@ -0,0 +1,216 @@
+import {logger} from '@shipfox/node-opentelemetry';
+import type {JiraApiClient} from '#api/client.js';
+import {
+  getJiraInstallationByConnectionId,
+  type JiraInstallationLock,
+  updateJiraInstallationWebhook,
+  withJiraInstallationLock,
+} from '#db/installations.js';
+
+export const JIRA_WEBHOOK_TTL_MS = 30 * 24 * 60 * 60 * 1000;
+
+export interface RegisterJiraWebhookParams {
+  jira: Pick<JiraApiClient, 'registerDynamicWebhook' | 'deleteDynamicWebhook'>;
+  connectionId: string;
+  cloudId: string;
+  accessToken: string;
+  webhookUrl: string;
+  now?: () => Date;
+  getInstallation?: typeof getJiraInstallationByConnectionId;
+  updateInstallation?: typeof updateJiraInstallationWebhook;
+  withRegistrationLock?: JiraInstallationLock;
+  onRegistrationSuccess?: (input: {tx?: unknown}) => Promise<void>;
+  onRegistrationFailure?: (input: {tx?: unknown}) => Promise<void>;
+}
+
+/** Register Jira's curated webhook and replace local metadata as one serialized state transition. */
+export async function registerJiraWebhook(
+  params: RegisterJiraWebhookParams,
+): Promise<{webhookId: number; webhookExpiresAt: Date}> {
+  const withRegistrationLock = params.withRegistrationLock ?? withJiraInstallationLock;
+  let callbackFailed = false;
+  let registeredWebhookId: number | undefined;
+  let previous: Awaited<ReturnType<typeof getJiraInstallationByConnectionId>>;
+  let metadataPersisted = false;
+  let cleanupSupersededWebhooks: (() => Promise<void>) | undefined;
+  let result: {webhookId: number; webhookExpiresAt: Date};
+  try {
+    result = await withRegistrationLock(params.cloudId, async () => {
+      try {
+        const getInstallation = params.getInstallation ?? getJiraInstallationByConnectionId;
+        previous = await getInstallation(params.connectionId);
+        const registration = await params.jira.registerDynamicWebhook({
+          accessToken: params.accessToken,
+          cloudId: params.cloudId,
+          url: params.webhookUrl,
+        });
+        registeredWebhookId = registration.webhookId;
+        const now = params.now ?? (() => new Date());
+        const webhookExpiresAt = new Date(now().getTime() + JIRA_WEBHOOK_TTL_MS);
+
+        const updateInstallation = params.updateInstallation ?? updateJiraInstallationWebhook;
+        const updateInput = {
+          connectionId: params.connectionId,
+          webhookIds: [...new Set([registration.webhookId, ...(previous?.webhookIds ?? [])])],
+          webhookExpiresAt,
+        };
+        const installation = await updateInstallation(updateInput);
+        if (!installation)
+          throw new Error('Jira webhook registration lost its installation record');
+        metadataPersisted = true;
+        await params.onRegistrationSuccess?.({});
+
+        cleanupSupersededWebhooks = () =>
+          finishSupersededWebhookCleanup(
+            params,
+            previous,
+            registration.webhookId,
+            webhookExpiresAt,
+          );
+        return {webhookId: registration.webhookId, webhookExpiresAt};
+      } catch (error) {
+        callbackFailed = true;
+        if (registeredWebhookId !== undefined) {
+          const deleted = await deleteNewWebhookAfterPersistenceFailure(
+            params,
+            registeredWebhookId,
+          );
+          if (metadataPersisted || !deleted) {
+            await restorePreviousWebhookMetadata(
+              params,
+              previous,
+              deleted ? undefined : registeredWebhookId,
+            );
+          }
+        } else if (metadataPersisted) {
+          await restorePreviousWebhookMetadata(params, previous);
+        }
+        await bestEffortRegistrationFailure(params);
+        throw error;
+      }
+    });
+  } catch (error) {
+    if (!callbackFailed) {
+      if (registeredWebhookId !== undefined) {
+        const deleted = await deleteNewWebhookAfterPersistenceFailure(params, registeredWebhookId);
+        if (metadataPersisted || !deleted) {
+          await restorePreviousWebhookMetadata(
+            params,
+            previous,
+            deleted ? undefined : registeredWebhookId,
+          );
+        }
+      } else if (metadataPersisted) {
+        await restorePreviousWebhookMetadata(params, previous);
+      }
+      await bestEffortRegistrationFailure(params);
+    }
+    throw error;
+  }
+
+  if (cleanupSupersededWebhooks) {
+    try {
+      await withRegistrationLock(params.cloudId, cleanupSupersededWebhooks);
+    } catch (error) {
+      logger().warn(
+        {err: error, connectionId: params.connectionId},
+        'Jira superseded webhook cleanup persistence failed',
+      );
+    }
+  }
+
+  return result;
+}
+
+async function finishSupersededWebhookCleanup(
+  params: RegisterJiraWebhookParams,
+  previous: Awaited<ReturnType<typeof getJiraInstallationByConnectionId>>,
+  registeredWebhookId: number,
+  webhookExpiresAt: Date,
+): Promise<void> {
+  const supersededWebhookIds = (previous?.webhookIds ?? []).filter(
+    (webhookId) => webhookId !== registeredWebhookId,
+  );
+  if (supersededWebhookIds.length === 0) return;
+
+  const failedCleanupIds: number[] = [];
+  for (const webhookId of supersededWebhookIds) {
+    try {
+      await params.jira.deleteDynamicWebhook({
+        accessToken: params.accessToken,
+        cloudId: params.cloudId,
+        webhookId,
+      });
+    } catch (error) {
+      failedCleanupIds.push(webhookId);
+      logger().warn(
+        {err: error, connectionId: params.connectionId, webhookId},
+        'Jira superseded webhook cleanup failed',
+      );
+    }
+  }
+
+  const retainedWebhookIds = [registeredWebhookId, ...failedCleanupIds];
+  const updateInstallation = params.updateInstallation ?? updateJiraInstallationWebhook;
+  const cleanupMetadata = await updateInstallation({
+    connectionId: params.connectionId,
+    webhookIds: retainedWebhookIds,
+    webhookExpiresAt,
+  });
+  if (!cleanupMetadata)
+    throw new Error('Jira webhook cleanup metadata persistence returned no installation');
+}
+
+async function bestEffortRegistrationFailure(params: RegisterJiraWebhookParams): Promise<void> {
+  try {
+    await params.onRegistrationFailure?.({});
+  } catch (error) {
+    logger().warn(
+      {err: error, connectionId: params.connectionId},
+      'Jira connection error-state update failed after webhook registration rejection',
+    );
+  }
+}
+
+async function restorePreviousWebhookMetadata(
+  params: RegisterJiraWebhookParams,
+  previous: Awaited<ReturnType<typeof getJiraInstallationByConnectionId>>,
+  retainedWebhookId?: number,
+): Promise<void> {
+  try {
+    const updateInstallation = params.updateInstallation ?? updateJiraInstallationWebhook;
+    await updateInstallation({
+      connectionId: params.connectionId,
+      webhookIds: [
+        ...(retainedWebhookId === undefined ? [] : [retainedWebhookId]),
+        ...(previous?.webhookIds ?? []).filter((webhookId) => webhookId !== retainedWebhookId),
+      ],
+      webhookExpiresAt: previous?.webhookExpiresAt ?? null,
+    });
+  } catch (error) {
+    logger().warn(
+      {err: error, connectionId: params.connectionId},
+      'Jira webhook metadata restoration failed after registration rejection',
+    );
+  }
+}
+
+async function deleteNewWebhookAfterPersistenceFailure(
+  params: RegisterJiraWebhookParams,
+  webhookId: number,
+): Promise<boolean> {
+  try {
+    await params.jira.deleteDynamicWebhook({
+      accessToken: params.accessToken,
+      cloudId: params.cloudId,
+      webhookId,
+    });
+    return true;
+  } catch (cleanupError) {
+    logger().warn(
+      {err: cleanupError, connectionId: params.connectionId, webhookId},
+      'Jira webhook cleanup failed after metadata persistence rejection',
+    );
+    return false;
+  }
+}

package/src/core/webhook.ts

@@ -0,0 +1,69 @@
+import type {JiraWebhookEnvelopeDto} from '@shipfox/api-integration-jira-dto';
+import type {
+  IntegrationConnection,
+  IntegrationTx,
+  PublishIntegrationEventReceivedFn,
+  RecordDeliveryOnlyFn,
+} from '@shipfox/api-integration-spi';
+import type {JiraInstallation} from '#db/installations.js';
+
+const JIRA_PROVIDER = 'jira';
+
+export interface HandleJiraWebhookParams {
+  tx: IntegrationTx;
+  deliveryId: string;
+  receivedAt: string;
+  rawPayload: JiraWebhookEnvelopeDto;
+  cloudId: string;
+  connection: IntegrationConnection<'jira'>;
+  authorizingAccountId: string;
+  publishIntegrationEventReceived: PublishIntegrationEventReceivedFn;
+  recordDeliveryOnly: RecordDeliveryOnlyFn;
+}
+
+export type HandleJiraWebhookResult = 'published' | 'duplicate' | 'discarded';
+
+export async function handleJiraWebhook(
+  params: HandleJiraWebhookParams,
+): Promise<HandleJiraWebhookResult> {
+  if (isSelfAuthoredEvent(params.rawPayload, params.authorizingAccountId)) {
+    await params.recordDeliveryOnly({
+      tx: params.tx,
+      provider: JIRA_PROVIDER,
+      deliveryId: params.deliveryId,
+    });
+    return 'discarded';
+  }
+
+  const payload = {...params.rawPayload, cloudId: params.cloudId};
+  const result = await params.publishIntegrationEventReceived({
+    tx: params.tx,
+    event: {
+      provider: JIRA_PROVIDER,
+      source: params.connection.slug,
+      event: params.rawPayload.webhookEvent,
+      workspaceId: params.connection.workspaceId,
+      connectionId: params.connection.id,
+      connectionName: params.connection.displayName,
+      deliveryId: params.deliveryId,
+      receivedAt: params.receivedAt,
+      payload,
+    },
+  });
+  return result.published ? 'published' : 'duplicate';
+}
+
+function isSelfAuthoredEvent(payload: JiraWebhookEnvelopeDto, authorizingAccountId: string) {
+  return (
+    (payload.webhookEvent === 'comment_created' ||
+      payload.webhookEvent === 'comment_updated' ||
+      payload.webhookEvent === 'jira:issue_updated') &&
+    payload.user.accountId === authorizingAccountId
+  );
+}
+
+export function isJiraInstallationUsable(
+  installation: JiraInstallation | undefined,
+): installation is JiraInstallation {
+  return installation?.status === 'installed';
+}

package/src/db/installations.test.ts

@@ -7,9 +7,13 @@ import {
   getJiraInstallationByCloudId,
   getJiraInstallationByConnectionId,
   getJiraInstallationByWebhookId,
+  listJiraInstallationsDueForTokenRefresh,
   markJiraInstallationRevoked,
+  markJiraInstallationTokenRefreshAttempt,
   updateJiraInstallationTokenExpiry,
+  updateJiraInstallationWebhook,
   upsertJiraInstallation,
+  withJiraWebhookRegistrationLock,
 } from './installations.js';
 
 function createInstallationInput(
@@ -62,6 +66,36 @@ describe('jira installations', () => {
     });
   });
 
+  it('preserves webhook metadata when reconnect upsert omits it', async () => {
+    const webhookExpiresAt = new Date('2030-01-01T00:00:00.000Z');
+    const input = createInstallationInput({webhookIds: [321], webhookExpiresAt});
+    await upsertJiraInstallation(input);
+
+    const result = await upsertJiraInstallation({
+      ...input,
+      scopes: ['read:jira-work', 'write:jira-work'],
+      webhookIds: undefined,
+      webhookExpiresAt: undefined,
+    });
+
+    expect(result.webhookIds).toEqual([321]);
+    expect(result.webhookExpiresAt).toEqual(webhookExpiresAt);
+  });
+
+  it('replaces webhook ids and expiry together after registration', async () => {
+    const input = createInstallationInput({webhookIds: [321]});
+    await upsertJiraInstallation(input);
+    const webhookExpiresAt = new Date('2030-02-01T00:00:00.000Z');
+
+    const result = await updateJiraInstallationWebhook({
+      connectionId: input.connectionId,
+      webhookIds: [654],
+      webhookExpiresAt,
+    });
+
+    expect(result).toMatchObject({webhookIds: [654], webhookExpiresAt});
+  });
+
   it('refuses to repoint a connection to a different Jira site', async () => {
     const first = createInstallationInput();
     await upsertJiraInstallation(first);
@@ -89,10 +123,19 @@ describe('jira installations', () => {
   });
 
   it('updates token metadata and deletes an installation', async () => {
-    const input = createInstallationInput();
-    await upsertJiraInstallation(input);
+    const input = createInstallationInput({
+      refreshTokenLastUsedAt: new Date('2020-01-01T00:00:00.000Z'),
+      refreshTokenLastAttemptedAt: new Date('2020-01-01T00:00:00.000Z'),
+    });
+    const initial = await upsertJiraInstallation(input);
     const tokenExpiresAt = new Date('2030-01-01T00:00:00.000Z');
 
+    const attempted = await markJiraInstallationTokenRefreshAttempt(input.connectionId);
+
+    expect(attempted?.refreshTokenLastAttemptedAt.getTime()).toBeGreaterThan(
+      initial.refreshTokenLastAttemptedAt.getTime(),
+    );
+
     const updated = await updateJiraInstallationTokenExpiry({
       connectionId: input.connectionId,
       tokenExpiresAt,
@@ -101,10 +144,81 @@ describe('jira installations', () => {
     const deleted = await deleteJiraInstallationByConnectionId(input.connectionId);
 
     expect(updated).toMatchObject({tokenExpiresAt, scopes: ['read:jira-work', 'write:jira-work']});
+    expect(updated?.refreshTokenLastUsedAt.getTime()).toBeGreaterThan(
+      initial.refreshTokenLastUsedAt.getTime(),
+    );
     expect(deleted).toBe(true);
     await expect(getJiraInstallationByConnectionId(input.connectionId)).resolves.toBeUndefined();
   });
 
+  it('lists only installed installations whose refresh tokens are nearing idle expiry', async () => {
+    const due = createInstallationInput({
+      refreshTokenLastUsedAt: new Date('2026-01-01T00:00:00.000Z'),
+    });
+    const fresh = createInstallationInput({
+      refreshTokenLastUsedAt: new Date('2026-07-01T00:00:00.000Z'),
+    });
+    const boundary = createInstallationInput({
+      refreshTokenLastUsedAt: new Date('2026-06-01T00:00:00.000Z'),
+    });
+    const revoked = createInstallationInput({
+      refreshTokenLastUsedAt: new Date('2026-01-01T00:00:00.000Z'),
+      status: 'revoked',
+    });
+    await upsertJiraInstallation(due);
+    await upsertJiraInstallation(fresh);
+    await upsertJiraInstallation(boundary);
+    await upsertJiraInstallation(revoked);
+
+    const result = await listJiraInstallationsDueForTokenRefresh({
+      before: new Date('2026-06-01T00:00:00.000Z'),
+    });
+
+    expect(result.map((installation) => installation.connectionId)).toContain(due.connectionId);
+    expect(result.map((installation) => installation.connectionId)).toContain(
+      boundary.connectionId,
+    );
+    expect(result.map((installation) => installation.connectionId)).not.toContain(
+      fresh.connectionId,
+    );
+    expect(result.map((installation) => installation.connectionId)).not.toContain(
+      revoked.connectionId,
+    );
+  });
+
+  it('orders due installations by their latest refresh attempt', async () => {
+    const refreshTokenLastUsedAt = new Date('1970-01-01T00:00:00.000Z');
+    const attemptBase = Date.now();
+    const latestAttempt = createInstallationInput({
+      refreshTokenLastUsedAt,
+      refreshTokenLastAttemptedAt: new Date(attemptBase + 3_000),
+    });
+    const middleAttempt = createInstallationInput({
+      refreshTokenLastUsedAt,
+      refreshTokenLastAttemptedAt: new Date(attemptBase + 2_000),
+    });
+    const oldestAttempt = createInstallationInput({
+      refreshTokenLastUsedAt,
+      refreshTokenLastAttemptedAt: new Date(attemptBase + 1_000),
+    });
+    await upsertJiraInstallation(latestAttempt);
+    await upsertJiraInstallation(middleAttempt);
+    await upsertJiraInstallation(oldestAttempt);
+
+    const result = await listJiraInstallationsDueForTokenRefresh({
+      before: new Date('2000-01-01T00:00:00.000Z'),
+      limit: 1_000,
+    });
+    const connectionIds = result.map((installation) => installation.connectionId);
+
+    expect(connectionIds.indexOf(oldestAttempt.connectionId)).toBeLessThan(
+      connectionIds.indexOf(middleAttempt.connectionId),
+    );
+    expect(connectionIds.indexOf(middleAttempt.connectionId)).toBeLessThan(
+      connectionIds.indexOf(latestAttempt.connectionId),
+    );
+  });
+
   it('returns undefined for unknown connection and webhook ids', async () => {
     const connectionId = crypto.randomUUID();
     const webhookId = Number.MAX_SAFE_INTEGER;
@@ -126,4 +240,36 @@ describe('jira installations', () => {
     expect(revoked?.status).toBe('revoked');
     expect(missing).toBeUndefined();
   });
+
+  it('serializes webhook registration lock contenders for one connection', async () => {
+    const connectionId = crypto.randomUUID();
+    let releaseFirst!: () => void;
+    let firstEntered!: () => void;
+    const firstReady = new Promise<void>((resolve) => {
+      firstEntered = resolve;
+    });
+    const firstRelease = new Promise<void>((resolve) => {
+      releaseFirst = resolve;
+    });
+
+    const first = withJiraWebhookRegistrationLock(connectionId, async () => {
+      firstEntered();
+      await firstRelease;
+      return 'first';
+    });
+    await firstReady;
+
+    let secondFinished = false;
+    const second = withJiraWebhookRegistrationLock(connectionId, () => {
+      secondFinished = true;
+      return Promise.resolve('second');
+    });
+    await Promise.resolve();
+    expect(secondFinished).toBe(false);
+
+    releaseFirst();
+    await expect(first).resolves.toBe('first');
+    await expect(second).resolves.toBe('second');
+    expect(secondFinished).toBe(true);
+  });
 });

package/src/db/installations.ts

@@ -1,6 +1,6 @@
 import {isUniqueViolation} from '@shipfox/node-drizzle';
-import {pgClient} from '@shipfox/node-postgres';
-import {eq, sql} from 'drizzle-orm';
+import {pgClient, withPostgresSession} from '@shipfox/node-postgres';
+import {and, asc, eq, lte, sql} from 'drizzle-orm';
 import {
   JiraConnectionAlreadyLinkedError,
   JiraInstallationAlreadyLinkedError,
@@ -9,6 +9,33 @@ import {
 import {db} from './db.js';
 import {jiraInstallations, toJiraInstallation} from './schema/installations.js';
 
+export type JiraInstallationLock = <T>(lockKey: string, fn: () => Promise<T>) => Promise<T>;
+
+const JIRA_ADVISORY_LOCK_RETRY_DELAY_MS = 100;
+const JIRA_ADVISORY_LOCK_MAX_RETRY_DELAY_MS = 1_000;
+const JIRA_ADVISORY_LOCK_TIMEOUT_MS = 30_000;
+
+type JiraAdvisoryLockAttempt<T> = {acquired: true; value: T} | {acquired: false};
+
+export function withJiraInstallationLock<T>(lockKey: string, fn: () => Promise<T>) {
+  const advisoryKey = `jira-installation:${lockKey}`;
+  return withJiraAdvisoryLockWait(`Jira installation lock: ${lockKey}`, () =>
+    withPostgresSession(async (client) => {
+      const lock = await client.query<{acquired: boolean}>(
+        'SELECT pg_try_advisory_lock(hashtext($1)) AS acquired',
+        [advisoryKey],
+      );
+      if (lock.rows[0]?.acquired !== true) return {acquired: false as const};
+
+      try {
+        return {acquired: true as const, value: await fn()};
+      } finally {
+        await client.query('SELECT pg_advisory_unlock(hashtext($1))', [advisoryKey]);
+      }
+    }),
+  );
+}
+
 export type JiraInstallationStatus = 'installed' | 'revoked';
 
 export interface JiraInstallation {
@@ -23,6 +50,8 @@ export interface JiraInstallation {
   webhookExpiresAt: Date | null;
   status: JiraInstallationStatus;
   tokenExpiresAt: Date | null;
+  refreshTokenLastUsedAt: Date;
+  refreshTokenLastAttemptedAt: Date;
   createdAt: Date;
   updatedAt: Date;
 }
@@ -38,6 +67,8 @@ export interface UpsertJiraInstallationParams {
   webhookExpiresAt?: Date | null | undefined;
   status: JiraInstallationStatus;
   tokenExpiresAt?: Date | null | undefined;
+  refreshTokenLastUsedAt?: Date | undefined;
+  refreshTokenLastAttemptedAt?: Date | undefined;
 }
 
 export interface UpdateJiraInstallationTokenExpiryParams {
@@ -46,6 +77,12 @@ export interface UpdateJiraInstallationTokenExpiryParams {
   scopes?: string[] | undefined;
 }
 
+export interface UpdateJiraInstallationWebhookParams {
+  connectionId: string;
+  webhookIds: number[];
+  webhookExpiresAt: Date | null;
+}
+
 type JiraDb = ReturnType<typeof db>;
 type JiraTx = Parameters<Parameters<JiraDb['transaction']>[0]>[0];
 
@@ -55,7 +92,6 @@ export async function upsertJiraInstallation(
 ): Promise<JiraInstallation> {
   const executor = (options.tx ?? db()) as JiraDb | JiraTx;
   const now = new Date();
-  const webhookIds = params.webhookIds ?? [];
   let row: typeof jiraInstallations.$inferSelect | undefined;
   try {
     [row] = await executor
@@ -67,10 +103,12 @@ export async function upsertJiraInstallation(
         siteName: params.siteName,
         authorizingAccountId: params.authorizingAccountId,
         scopes: params.scopes,
-        webhookIds,
+        webhookIds: params.webhookIds ?? [],
         webhookExpiresAt: params.webhookExpiresAt ?? null,
         status: params.status,
         tokenExpiresAt: params.tokenExpiresAt ?? null,
+        refreshTokenLastUsedAt: params.refreshTokenLastUsedAt ?? now,
+        refreshTokenLastAttemptedAt: params.refreshTokenLastAttemptedAt ?? now,
       })
       .onConflictDoUpdate({
         target: jiraInstallations.connectionId,
@@ -81,10 +119,14 @@ export async function upsertJiraInstallation(
           siteName: params.siteName,
           authorizingAccountId: params.authorizingAccountId,
           scopes: params.scopes,
-          webhookIds,
-          webhookExpiresAt: params.webhookExpiresAt ?? null,
+          ...(params.webhookIds === undefined ? {} : {webhookIds: params.webhookIds}),
+          ...(params.webhookExpiresAt === undefined
+            ? {}
+            : {webhookExpiresAt: params.webhookExpiresAt}),
           status: params.status,
           tokenExpiresAt: params.tokenExpiresAt ?? null,
+          refreshTokenLastUsedAt: params.refreshTokenLastUsedAt ?? now,
+          refreshTokenLastAttemptedAt: params.refreshTokenLastAttemptedAt ?? now,
           updatedAt: now,
         },
       })
@@ -122,11 +164,63 @@ export async function updateJiraInstallationTokenExpiry(
   options: {tx?: unknown} = {},
 ): Promise<JiraInstallation | undefined> {
   const executor = (options.tx ?? db()) as JiraDb | JiraTx;
+  const now = new Date();
   const [row] = await executor
     .update(jiraInstallations)
     .set({
       tokenExpiresAt: params.tokenExpiresAt,
+      refreshTokenLastUsedAt: now,
+      refreshTokenLastAttemptedAt: now,
       ...(params.scopes === undefined ? {} : {scopes: params.scopes}),
+      updatedAt: now,
+    })
+    .where(eq(jiraInstallations.connectionId, params.connectionId))
+    .returning();
+  return row ? toJiraInstallation(row) : undefined;
+}
+
+export async function markJiraInstallationTokenRefreshAttempt(
+  connectionId: string,
+  options: {tx?: unknown} = {},
+): Promise<JiraInstallation | undefined> {
+  const executor = (options.tx ?? db()) as JiraDb | JiraTx;
+  const [row] = await executor
+    .update(jiraInstallations)
+    .set({refreshTokenLastAttemptedAt: new Date()})
+    .where(eq(jiraInstallations.connectionId, connectionId))
+    .returning();
+  return row ? toJiraInstallation(row) : undefined;
+}
+
+export async function listJiraInstallationsDueForTokenRefresh(
+  params: {before: Date; limit?: number | undefined},
+  options: {tx?: unknown} = {},
+): Promise<JiraInstallation[]> {
+  const executor = (options.tx ?? db()) as JiraDb | JiraTx;
+  const rows = await executor
+    .select()
+    .from(jiraInstallations)
+    .where(
+      and(
+        eq(jiraInstallations.status, 'installed'),
+        lte(jiraInstallations.refreshTokenLastUsedAt, params.before),
+      ),
+    )
+    .orderBy(asc(jiraInstallations.refreshTokenLastAttemptedAt))
+    .limit(params.limit ?? 100);
+  return rows.map(toJiraInstallation);
+}
+
+export async function updateJiraInstallationWebhook(
+  params: UpdateJiraInstallationWebhookParams,
+  options: {tx?: unknown} = {},
+): Promise<JiraInstallation | undefined> {
+  const executor = (options.tx ?? db()) as JiraDb | JiraTx;
+  const [row] = await executor
+    .update(jiraInstallations)
+    .set({
+      webhookIds: params.webhookIds,
+      webhookExpiresAt: params.webhookExpiresAt,
       updatedAt: new Date(),
     })
     .where(eq(jiraInstallations.connectionId, params.connectionId))
@@ -145,7 +239,7 @@ export async function deleteJiraInstallationByConnectionId(
   return (result.rowCount ?? 0) > 0;
 }
 
-export type JiraRefreshLockResult<T> = {acquired: true; value: T} | {acquired: false};
+export type JiraRefreshLockResult<T> = JiraAdvisoryLockAttempt<T>;
 
 export function withJiraRefreshLock<T>(
   connectionId: string,
@@ -154,6 +248,22 @@ export function withJiraRefreshLock<T>(
   return withJiraRefreshLockClient(connectionId, fn);
 }
 
+export function withJiraRefreshLockAndWait<T>(
+  connectionId: string,
+  fn: () => Promise<T>,
+): Promise<T> {
+  return withJiraAdvisoryLockWait(`Jira refresh lock: ${connectionId}`, () =>
+    withJiraRefreshLock(connectionId, fn),
+  );
+}
+
+export function withJiraWebhookRegistrationLock<T>(
+  lockKey: string,
+  fn: (tx?: unknown) => Promise<T>,
+): Promise<T> {
+  return withJiraInstallationLock(lockKey, () => fn());
+}
+
 async function withJiraRefreshLockClient<T>(
   connectionId: string,
   fn: () => Promise<T>,
@@ -177,6 +287,22 @@ async function withJiraRefreshLockClient<T>(
   }
 }
 
+async function withJiraAdvisoryLockWait<T>(
+  lockDescription: string,
+  attemptLock: () => Promise<JiraAdvisoryLockAttempt<T>>,
+): Promise<T> {
+  const deadline = Date.now() + JIRA_ADVISORY_LOCK_TIMEOUT_MS;
+  let retryDelayMs = JIRA_ADVISORY_LOCK_RETRY_DELAY_MS;
+
+  while (true) {
+    const attempt = await attemptLock();
+    if (attempt.acquired) return attempt.value;
+    if (Date.now() >= deadline) throw new Error(`Timed out waiting for ${lockDescription}`);
+    await new Promise((resolve) => setTimeout(resolve, retryDelayMs));
+    retryDelayMs = Math.min(retryDelayMs * 2, JIRA_ADVISORY_LOCK_MAX_RETRY_DELAY_MS);
+  }
+}
+
 export async function getJiraInstallationByConnectionId(
   connectionId: string,
   options: {tx?: unknown} = {},