@shipfox/api-integration-jira 4.0.0

package/drizzle/0000_whole_master_chief.sql

@@ -0,0 +1,18 @@
+CREATE TABLE "integrations_jira_installations" (
+	"id" uuid PRIMARY KEY DEFAULT uuidv7() NOT NULL,
+	"connection_id" uuid NOT NULL,
+	"cloud_id" text NOT NULL,
+	"site_url" text NOT NULL,
+	"site_name" text NOT NULL,
+	"authorizing_account_id" text NOT NULL,
+	"scopes" jsonb NOT NULL,
+	"webhook_ids" jsonb DEFAULT '[]'::jsonb NOT NULL,
+	"webhook_expires_at" timestamp with time zone,
+	"status" text NOT NULL,
+	"token_expires_at" timestamp with time zone,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE UNIQUE INDEX "integrations_jira_installations_connection_unique" ON "integrations_jira_installations" USING btree ("connection_id");--> statement-breakpoint
+CREATE INDEX "integrations_jira_installations_cloud_id_idx" ON "integrations_jira_installations" USING btree ("cloud_id");

package/drizzle/meta/0000_snapshot.json

@@ -0,0 +1,145 @@
+{
+  "id": "5903a3ad-8572-4443-9fb4-8eb0298fab14",
+  "prevId": "00000000-0000-0000-0000-000000000000",
+  "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
+        },
+        "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_idx": {
+          "name": "integrations_jira_installations_cloud_id_idx",
+          "columns": [
+            {
+              "expression": "cloud_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    }
+  },
+  "enums": {},
+  "schemas": {},
+  "sequences": {},
+  "roles": {},
+  "policies": {},
+  "views": {},
+  "_meta": {
+    "columns": {},
+    "schemas": {},
+    "tables": {}
+  }
+}

package/drizzle/meta/_journal.json

@@ -0,0 +1,13 @@
+{
+  "version": "7",
+  "dialect": "postgresql",
+  "entries": [
+    {
+      "idx": 0,
+      "version": "7",
+      "when": 1784385935754,
+      "tag": "0000_whole_master_chief",
+      "breakpoints": true
+    }
+  ]
+}

package/drizzle.config.ts

@@ -0,0 +1,7 @@
+import {defineConfig} from 'drizzle-kit';
+
+export default defineConfig({
+  schema: './src/db/schema/*.ts',
+  out: './drizzle',
+  dialect: 'postgresql',
+});

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@shipfox/api-integration-jira",
+  "license": "MIT",
+  "version": "4.0.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ShipfoxHQ/shipfox.git",
+    "directory": "libs/api/integration/jira"
+  },
+  "private": false,
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "imports": {
+    "#test/*": "./test/*",
+    "#*": {
+      "workspace-source": "./src/*",
+      "development": "./src/*",
+      "default": "./dist/*"
+    }
+  },
+  "exports": {
+    ".": {
+      "development": {
+        "types": "./src/index.ts",
+        "default": "./src/index.ts"
+      },
+      "default": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    }
+  },
+  "dependencies": {
+    "drizzle-orm": "^0.45.2",
+    "@shipfox/api-integration-jira-dto": "4.0.0",
+    "@shipfox/node-drizzle": "0.3.0",
+    "@shipfox/config": "1.2.1",
+    "@shipfox/node-postgres": "0.4.1"
+  },
+  "peerDependencies": {
+    "@shipfox/api-secrets": "4.0.0"
+  },
+  "devDependencies": {
+    "@types/pg": "^8.15.5",
+    "drizzle-kit": "^0.31.10",
+    "fishery": "^2.4.0",
+    "@shipfox/swc": "1.2.5",
+    "@shipfox/biome": "1.8.1",
+    "@shipfox/typescript": "1.1.6",
+    "@shipfox/vitest": "1.2.2",
+    "@shipfox/ts-config": "1.3.8"
+  },
+  "scripts": {
+    "build": "shipfox-swc",
+    "check": "shipfox-biome-check",
+    "check:fix": "shipfox-biome-check --write",
+    "test": "shipfox-vitest-run",
+    "test:watch": "shipfox-vitest-watch",
+    "type": "shipfox-tsc-check",
+    "type:emit": "shipfox-tsc-emit"
+  }
+}

package/src/config.test.ts

@@ -0,0 +1,37 @@
+const jiraEnvNames = [
+  'JIRA_OAUTH_CLIENT_ID',
+  'JIRA_OAUTH_CLIENT_SECRET',
+  'JIRA_OAUTH_REDIRECT_URL',
+  'JIRA_WEBHOOK_SIGNING_SECRET',
+  'JIRA_WEBHOOK_BASE_URL',
+] as const;
+
+describe('jira config', () => {
+  afterEach(() => {
+    vi.unstubAllEnvs();
+    vi.resetModules();
+  });
+
+  it('exports validated Jira config with the default API and auth URLs', async () => {
+    vi.stubEnv('JIRA_API_BASE_URL', undefined);
+    vi.stubEnv('JIRA_AUTH_BASE_URL', undefined);
+    vi.resetModules();
+
+    const {config} = await import('#index.js');
+
+    for (const name of jiraEnvNames) expect(config[name]).toBe(process.env[name]);
+    expect(config.JIRA_API_BASE_URL).toBe('https://api.atlassian.com');
+    expect(config.JIRA_AUTH_BASE_URL).toBe('https://auth.atlassian.com');
+  });
+
+  it('accepts compatible Jira API and auth URL overrides', async () => {
+    vi.stubEnv('JIRA_API_BASE_URL', 'https://jira-api.example.test');
+    vi.stubEnv('JIRA_AUTH_BASE_URL', 'https://jira-auth.example.test');
+    vi.resetModules();
+
+    const {config} = await import('#index.js');
+
+    expect(config.JIRA_API_BASE_URL).toBe('https://jira-api.example.test');
+    expect(config.JIRA_AUTH_BASE_URL).toBe('https://jira-auth.example.test');
+  });
+});

package/src/config.ts

@@ -0,0 +1,27 @@
+import {createConfig, str, url} from '@shipfox/config';
+
+export const config = createConfig({
+  JIRA_OAUTH_CLIENT_ID: str({
+    desc: 'OAuth client ID of the Jira app, used to start and complete the Jira connect flow. Required.',
+  }),
+  JIRA_OAUTH_CLIENT_SECRET: str({
+    desc: 'OAuth client secret of the Jira app, used to exchange authorization codes for access and refresh tokens. Required.',
+  }),
+  JIRA_OAUTH_REDIRECT_URL: url({
+    desc: 'Public client callback URL Jira redirects to after OAuth authorization, such as https://shipfox.example.com/integrations/jira/callback. Required.',
+  }),
+  JIRA_WEBHOOK_SIGNING_SECRET: str({
+    desc: 'Secret used to verify incoming Jira webhooks. It must match the webhook signing secret configured for the Jira app. Required.',
+  }),
+  JIRA_WEBHOOK_BASE_URL: url({
+    desc: 'Public base URL Jira sends webhooks to. Its origin must be added to the Jira app webhook allowlist. Required.',
+  }),
+  JIRA_API_BASE_URL: url({
+    desc: 'Jira API base URL. Override this only when routing Jira API requests through a proxy or test server.',
+    default: 'https://api.atlassian.com',
+  }),
+  JIRA_AUTH_BASE_URL: url({
+    desc: 'Jira OAuth base URL. Override this only when routing OAuth requests through a proxy or test server.',
+    default: 'https://auth.atlassian.com',
+  }),
+});

package/src/core/errors.ts

@@ -0,0 +1,22 @@
+export class JiraConnectionNotFoundError extends Error {
+  constructor(connectionId: string) {
+    super(`Jira integration connection was not found: ${connectionId}`);
+    this.name = 'JiraConnectionNotFoundError';
+  }
+}
+
+export class JiraAccessTokenMissingError extends Error {
+  constructor(connectionId: string) {
+    super(`Jira access token is missing for connection: ${connectionId}`);
+    this.name = 'JiraAccessTokenMissingError';
+  }
+}
+
+export class JiraInstallationSiteMismatchError extends Error {
+  constructor(connectionId: string, cloudId: string) {
+    super(
+      `Jira connection is already linked to a different site: ${connectionId} (attempted ${cloudId})`,
+    );
+    this.name = 'JiraInstallationSiteMismatchError';
+  }
+}

package/src/core/tokens.test.ts

@@ -0,0 +1,106 @@
+import {JiraAccessTokenMissingError, JiraConnectionNotFoundError} from '#core/errors.js';
+import {
+  createJiraTokenStore,
+  type JiraConnectionResolverResult,
+  type JiraSecretsStore,
+  jiraSecretsNamespace,
+} from './tokens.js';
+
+let secrets: JiraSecretsStore;
+
+beforeAll(async () => {
+  secrets = await import('@shipfox/api-secrets');
+});
+
+function createConnectionContext() {
+  const workspaceId = crypto.randomUUID();
+  const connectionId = crypto.randomUUID();
+  const resolveConnection = vi
+    .fn<(connectionId: string) => Promise<JiraConnectionResolverResult | undefined>>()
+    .mockResolvedValue({workspaceId});
+  const store = createJiraTokenStore({resolveConnection, secrets});
+
+  return {workspaceId, connectionId, resolveConnection, store};
+}
+
+function storedToken(input: {
+  workspaceId: string;
+  connectionId: string;
+  key: 'ACCESS_TOKEN' | 'REFRESH_TOKEN';
+}) {
+  return secrets.getSecret({
+    workspaceId: input.workspaceId,
+    namespace: jiraSecretsNamespace(input.connectionId),
+    key: input.key,
+  });
+}
+
+describe('createJiraTokenStore.storeTokens', () => {
+  it('stores access and refresh tokens in the Jira system namespace', async () => {
+    const {workspaceId, connectionId, store} = createConnectionContext();
+
+    await store.storeTokens({
+      connectionId,
+      accessToken: 'access-token',
+      refreshToken: 'refresh-token',
+      editedBy: crypto.randomUUID(),
+    });
+
+    await expect(storedToken({workspaceId, connectionId, key: 'ACCESS_TOKEN'})).resolves.toBe(
+      'access-token',
+    );
+    await expect(storedToken({workspaceId, connectionId, key: 'REFRESH_TOKEN'})).resolves.toBe(
+      'refresh-token',
+    );
+  });
+
+  it('stores only the access token when no refresh token was issued', async () => {
+    const {workspaceId, connectionId, store} = createConnectionContext();
+
+    await store.storeTokens({connectionId, accessToken: 'access-token'});
+
+    await expect(storedToken({workspaceId, connectionId, key: 'ACCESS_TOKEN'})).resolves.toBe(
+      'access-token',
+    );
+    await expect(
+      storedToken({workspaceId, connectionId, key: 'REFRESH_TOKEN'}),
+    ).resolves.toBeNull();
+  });
+
+  it('throws a typed error when the connection cannot be resolved', async () => {
+    const {connectionId, resolveConnection, store} = createConnectionContext();
+    resolveConnection.mockResolvedValue(undefined);
+
+    const result = store.storeTokens({connectionId, accessToken: 'access-token'});
+
+    await expect(result).rejects.toBeInstanceOf(JiraConnectionNotFoundError);
+  });
+});
+
+describe('createJiraTokenStore.getAccessToken', () => {
+  it('returns the stored access token', async () => {
+    const {connectionId, store} = createConnectionContext();
+    await store.storeTokens({connectionId, accessToken: 'access-token'});
+
+    const result = await store.getAccessToken({connectionId});
+
+    expect(result).toBe('access-token');
+  });
+
+  it('throws a typed error when no access token is stored', async () => {
+    const {connectionId, store} = createConnectionContext();
+
+    const result = store.getAccessToken({connectionId});
+
+    await expect(result).rejects.toBeInstanceOf(JiraAccessTokenMissingError);
+  });
+
+  it('throws a typed error when the connection cannot be resolved', async () => {
+    const {connectionId, resolveConnection, store} = createConnectionContext();
+    resolveConnection.mockResolvedValue(undefined);
+
+    const result = store.getAccessToken({connectionId});
+
+    await expect(result).rejects.toBeInstanceOf(JiraConnectionNotFoundError);
+  });
+});

package/src/core/tokens.ts

@@ -0,0 +1,77 @@
+import {JiraAccessTokenMissingError, JiraConnectionNotFoundError} from '#core/errors.js';
+
+const ACCESS_TOKEN_KEY = 'ACCESS_TOKEN';
+const REFRESH_TOKEN_KEY = 'REFRESH_TOKEN';
+
+export interface JiraConnectionResolverResult {
+  workspaceId: string;
+}
+
+export interface JiraSecretsStore {
+  getSecret(params: {workspaceId: string; namespace: string; key: string}): Promise<string | null>;
+  setSecrets(params: {
+    workspaceId: string;
+    namespace: string;
+    values: Record<string, string>;
+    editedBy?: string | null | undefined;
+  }): Promise<void>;
+}
+
+export interface CreateJiraTokenStoreParams {
+  resolveConnection(connectionId: string): Promise<JiraConnectionResolverResult | undefined>;
+  secrets: JiraSecretsStore;
+}
+
+export interface StoreJiraTokensParams {
+  connectionId: string;
+  accessToken: string;
+  refreshToken?: string | undefined;
+  editedBy?: string | null | undefined;
+}
+
+export interface GetJiraAccessTokenParams {
+  connectionId: string;
+}
+
+export interface JiraTokenStore {
+  storeTokens(params: StoreJiraTokensParams): Promise<void>;
+  getAccessToken(params: GetJiraAccessTokenParams): Promise<string>;
+}
+
+export function jiraSecretsNamespace(connectionId: string): string {
+  return `system/integrations/jira/${connectionId}`;
+}
+
+export function createJiraTokenStore(params: CreateJiraTokenStoreParams): JiraTokenStore {
+  async function resolveWorkspaceId(connectionId: string): Promise<string> {
+    const connection = await params.resolveConnection(connectionId);
+    if (!connection) throw new JiraConnectionNotFoundError(connectionId);
+    return connection.workspaceId;
+  }
+
+  return {
+    async storeTokens(input) {
+      const workspaceId = await resolveWorkspaceId(input.connectionId);
+      const values: Record<string, string> = {[ACCESS_TOKEN_KEY]: input.accessToken};
+      if (input.refreshToken) values[REFRESH_TOKEN_KEY] = input.refreshToken;
+
+      await params.secrets.setSecrets({
+        workspaceId,
+        namespace: jiraSecretsNamespace(input.connectionId),
+        values,
+        editedBy: input.editedBy,
+      });
+    },
+
+    async getAccessToken(input) {
+      const workspaceId = await resolveWorkspaceId(input.connectionId);
+      const token = await params.secrets.getSecret({
+        workspaceId,
+        namespace: jiraSecretsNamespace(input.connectionId),
+        key: ACCESS_TOKEN_KEY,
+      });
+      if (!token) throw new JiraAccessTokenMissingError(input.connectionId);
+      return token;
+    },
+  };
+}

package/src/db/db.ts

@@ -0,0 +1,16 @@
+import {drizzle, type NodePgDatabase} from '@shipfox/node-drizzle';
+import {pgClient} from '@shipfox/node-postgres';
+import {jiraInstallations} from './schema/installations.js';
+
+export const schema = {jiraInstallations};
+
+let database: NodePgDatabase<typeof schema> | undefined;
+
+export function db() {
+  if (!database) database = drizzle(pgClient(), {schema});
+  return database;
+}
+
+export function closeDb(): void {
+  database = undefined;
+}

package/src/db/installations.test.ts

@@ -0,0 +1,93 @@
+import {JiraInstallationSiteMismatchError} from '#core/errors.js';
+import {
+  getJiraInstallationByConnectionId,
+  getJiraInstallationByWebhookId,
+  markJiraInstallationRevoked,
+  upsertJiraInstallation,
+} from './installations.js';
+
+function createInstallationInput(
+  overrides: Partial<Parameters<typeof upsertJiraInstallation>[0]> = {},
+) {
+  return {
+    connectionId: crypto.randomUUID(),
+    cloudId: crypto.randomUUID(),
+    siteUrl: 'https://acme.atlassian.net',
+    siteName: 'Acme',
+    authorizingAccountId: crypto.randomUUID(),
+    scopes: ['read:jira-work'],
+    webhookIds: [Math.floor(Math.random() * Number.MAX_SAFE_INTEGER)],
+    status: 'installed' as const,
+    ...overrides,
+  };
+}
+
+describe('jira installations', () => {
+  it('inserts an installation and reads it by connection and webhook id', async () => {
+    const webhookId = Math.floor(Math.random() * Number.MAX_SAFE_INTEGER);
+    const input = createInstallationInput({webhookIds: [webhookId]});
+
+    const installation = await upsertJiraInstallation(input);
+    const byConnection = await getJiraInstallationByConnectionId(input.connectionId);
+    const byWebhook = await getJiraInstallationByWebhookId(webhookId);
+
+    expect(byConnection).toEqual(installation);
+    expect(byWebhook).toEqual(installation);
+  });
+
+  it('updates mutable metadata for the same connection and Jira site', async () => {
+    const input = createInstallationInput();
+    await upsertJiraInstallation(input);
+
+    const result = await upsertJiraInstallation({
+      ...input,
+      siteUrl: 'https://renamed.atlassian.net',
+      siteName: 'Acme renamed',
+      authorizingAccountId: crypto.randomUUID(),
+      scopes: ['read:jira-work', 'write:jira-work'],
+      webhookIds: [123],
+    });
+
+    expect(result).toMatchObject({
+      siteUrl: 'https://renamed.atlassian.net',
+      siteName: 'Acme renamed',
+      scopes: ['read:jira-work', 'write:jira-work'],
+      webhookIds: [123],
+    });
+  });
+
+  it('refuses to repoint a connection to a different Jira site', async () => {
+    const first = createInstallationInput();
+    await upsertJiraInstallation(first);
+    const second = createInstallationInput({connectionId: first.connectionId});
+
+    const result = upsertJiraInstallation(second);
+
+    await expect(result).rejects.toBeInstanceOf(JiraInstallationSiteMismatchError);
+    await expect(getJiraInstallationByConnectionId(first.connectionId)).resolves.toMatchObject({
+      cloudId: first.cloudId,
+    });
+  });
+
+  it('returns undefined for unknown connection and webhook ids', async () => {
+    const connectionId = crypto.randomUUID();
+    const webhookId = Number.MAX_SAFE_INTEGER;
+
+    const byConnection = await getJiraInstallationByConnectionId(connectionId);
+    const byWebhook = await getJiraInstallationByWebhookId(webhookId);
+
+    expect(byConnection).toBeUndefined();
+    expect(byWebhook).toBeUndefined();
+  });
+
+  it('marks an installation revoked and returns undefined for an unknown connection', async () => {
+    const input = createInstallationInput();
+    await upsertJiraInstallation(input);
+
+    const revoked = await markJiraInstallationRevoked(input.connectionId);
+    const missing = await markJiraInstallationRevoked(crypto.randomUUID());
+
+    expect(revoked?.status).toBe('revoked');
+    expect(missing).toBeUndefined();
+  });
+});