@shipfox/api-integration-jira 4.0.0 → 5.0.0

package/src/presentation/routes/errors.ts

@@ -0,0 +1,61 @@
+import {
+  ConnectionSlugConflictError,
+  type IntegrationProviderErrorReason,
+} from '@shipfox/api-integration-core-dto';
+import {ClientError} from '@shipfox/node-fastify';
+import {
+  JiraAuthorizationScopeMismatchError,
+  JiraConnectionAlreadyLinkedError,
+  JiraInstallationAlreadyLinkedError,
+  JiraInstallStateActorMismatchError,
+  JiraInstallStateError,
+  JiraIntegrationProviderError,
+  JiraOAuthCallbackError,
+  JiraOfflineAccessNotGrantedError,
+  JiraPendingSelectionNotFoundError,
+  JiraSiteSelectionMismatchError,
+} from '#core/errors.js';
+
+function providerStatus(reason: IntegrationProviderErrorReason): number {
+  if (reason === 'rate-limited') return 429;
+  if (reason === 'timeout' || reason === 'provider-unavailable') return 503;
+  return 422;
+}
+
+export function jiraRouteErrorHandler(error: unknown): never {
+  if (error instanceof JiraInstallStateError)
+    throw new ClientError(error.message, 'invalid-jira-install-state', {status: 400});
+  if (error instanceof JiraInstallStateActorMismatchError)
+    throw new ClientError(error.message, 'jira-install-state-actor-mismatch', {status: 403});
+  if (error instanceof JiraInstallationAlreadyLinkedError)
+    throw new ClientError(error.message, 'jira-installation-already-linked', {status: 409});
+  if (error instanceof JiraConnectionAlreadyLinkedError)
+    throw new ClientError(error.message, 'jira-connection-already-linked', {status: 409});
+  if (error instanceof JiraAuthorizationScopeMismatchError)
+    throw new ClientError(error.message, 'jira-authorization-scope-mismatch', {
+      status: 422,
+      details: {missing_scopes: error.missingScopes},
+    });
+  if (error instanceof JiraOfflineAccessNotGrantedError)
+    throw new ClientError(error.message, 'jira-offline-access-not-granted', {status: 422});
+  if (error instanceof JiraSiteSelectionMismatchError)
+    throw new ClientError(error.message, 'jira-site-selection-mismatch', {status: 422});
+  if (error instanceof JiraPendingSelectionNotFoundError)
+    throw new ClientError(error.message, 'jira-pending-selection-not-found', {status: 410});
+  if (error instanceof JiraOAuthCallbackError)
+    throw new ClientError(error.message, 'jira-oauth-callback-error', {
+      status: 422,
+      details: {
+        error: error.providerError,
+        ...(error.providerDescription ? {error_description: error.providerDescription} : {}),
+      },
+    });
+  if (error instanceof ConnectionSlugConflictError)
+    throw new ClientError(error.message, 'slug-conflict', {status: 409});
+  if (error instanceof JiraIntegrationProviderError)
+    throw new ClientError(error.message, error.reason, {
+      status: providerStatus(error.reason),
+      details: {retry_after_seconds: error.retryAfterSeconds},
+    });
+  throw error;
+}

package/src/presentation/routes/install.ts

@@ -0,0 +1,147 @@
+import {AUTH_USER, requireUserContext, requireWorkspaceAccess} from '@shipfox/api-auth-context';
+import {
+  type IntegrationCapability,
+  type IntegrationConnection,
+  integrationConnectionDtoSchema,
+} from '@shipfox/api-integration-core-dto';
+import {
+  completeJiraSiteSelectionBodySchema,
+  createJiraInstallBodySchema,
+  createJiraInstallResponseSchema,
+  type JiraCallbackQueryDto,
+  jiraCallbackQuerySchema,
+  jiraCallbackResponseSchema,
+} from '@shipfox/api-integration-jira-dto';
+import {requireWorkspaceMembership} from '@shipfox/api-workspaces';
+import {defineRoute, type RouteGroup} from '@shipfox/node-fastify';
+import type {JiraApiClient} from '#api/client.js';
+import {config} from '#config.js';
+import {
+  type ConnectJiraInstallationInput,
+  handleJiraCallback,
+  handleJiraOAuthCallbackError,
+  handleJiraSiteSelection,
+} from '#core/install.js';
+import type {JiraPendingSelectionStore} from '#core/pending.js';
+import {formatJiraOAuthScopes} from '#core/scopes.js';
+import {signJiraInstallState} from '#core/state.js';
+import type {JiraTokenStore} from '#core/tokens.js';
+import {toIntegrationConnectionDto} from '#presentation/dto/integrations.js';
+import {jiraRouteErrorHandler} from './errors.js';
+
+export interface CreateJiraIntegrationRoutesOptions {
+  jira: JiraApiClient;
+  tokenStore: Pick<JiraTokenStore, 'storeTokens'>;
+  pendingStore: Pick<JiraPendingSelectionStore, 'save' | 'load' | 'clear'>;
+  getExistingJiraConnection(input: {
+    cloudId: string;
+  }): Promise<IntegrationConnection<'jira'> | undefined>;
+  connectJiraInstallation(
+    input: ConnectJiraInstallationInput,
+  ): Promise<IntegrationConnection<'jira'>>;
+  disconnectJiraInstallation(input: {connectionId: string}): Promise<void>;
+  connectionCapabilities: IntegrationCapability[];
+}
+
+export function createJiraIntegrationRoutes(
+  options: CreateJiraIntegrationRoutesOptions,
+): RouteGroup {
+  const installRoute = defineRoute({
+    method: 'POST',
+    path: '/install',
+    auth: AUTH_USER,
+    description: 'Create a Jira OAuth authorization URL for a workspace.',
+    schema: {body: createJiraInstallBodySchema, response: {200: createJiraInstallResponseSchema}},
+    handler: (request) => {
+      const {workspace_id: workspaceId} = request.body;
+      const actor = requireUserContext(request);
+      requireWorkspaceAccess({request, workspaceId});
+      const installUrl = new URL(`${config.JIRA_AUTH_BASE_URL}/authorize`);
+      installUrl.searchParams.set('audience', 'api.atlassian.com');
+      installUrl.searchParams.set('client_id', config.JIRA_OAUTH_CLIENT_ID);
+      installUrl.searchParams.set('scope', formatJiraOAuthScopes());
+      installUrl.searchParams.set('redirect_uri', config.JIRA_OAUTH_REDIRECT_URL);
+      installUrl.searchParams.set(
+        'state',
+        signJiraInstallState({workspaceId, userId: actor.userId}),
+      );
+      installUrl.searchParams.set('response_type', 'code');
+      installUrl.searchParams.set('prompt', 'consent');
+      return {install_url: installUrl.toString()};
+    },
+  });
+  const callbackApiRoute = defineRoute({
+    method: 'GET',
+    path: '/callback/api',
+    auth: AUTH_USER,
+    description: 'Handle the Jira OAuth callback.',
+    schema: {querystring: jiraCallbackQuerySchema, response: {200: jiraCallbackResponseSchema}},
+    errorHandler: jiraRouteErrorHandler,
+    handler: async (request) => {
+      const actor = requireUserContext(request);
+      const query = request.query;
+      if (isJiraOAuthErrorCallback(query))
+        return await handleJiraOAuthCallbackError({
+          state: query.state,
+          error: query.error,
+          errorDescription: query.error_description,
+          sessionUserId: actor.userId,
+          sessionMemberships: actor.memberships,
+          requireWorkspaceMembership,
+        });
+      const result = await handleJiraCallback({
+        ...options,
+        code: query.code,
+        state: query.state,
+        sessionUserId: actor.userId,
+        sessionMemberships: actor.memberships,
+        requireWorkspaceMembership,
+      });
+      return 'sites' in result
+        ? {
+            sites: result.sites.map((site) => ({
+              cloud_id: site.cloudId,
+              name: site.name,
+              url: site.url,
+              scopes: site.scopes,
+            })),
+          }
+        : toIntegrationConnectionDto(result, {capabilities: options.connectionCapabilities});
+    },
+  });
+  const siteSelectionRoute = defineRoute({
+    method: 'POST',
+    path: '/callback/site',
+    auth: AUTH_USER,
+    description: 'Complete Jira OAuth site selection.',
+    schema: {
+      body: completeJiraSiteSelectionBodySchema,
+      response: {200: integrationConnectionDtoSchema},
+    },
+    errorHandler: jiraRouteErrorHandler,
+    handler: async (request) => {
+      const actor = requireUserContext(request);
+      const connection = await handleJiraSiteSelection({
+        ...options,
+        cloudId: request.body.cloud_id,
+        state: request.body.state,
+        sessionUserId: actor.userId,
+        sessionMemberships: actor.memberships,
+        requireWorkspaceMembership,
+      });
+      return toIntegrationConnectionDto(connection, {capabilities: options.connectionCapabilities});
+    },
+  });
+  return {
+    prefix: '/integrations/jira',
+    routes: [installRoute, callbackApiRoute, siteSelectionRoute],
+  };
+}
+
+function isJiraOAuthErrorCallback(query: JiraCallbackQueryDto): query is JiraCallbackQueryDto & {
+  error: string;
+  error_description?: string | undefined;
+  state: string;
+} {
+  return 'error' in query && typeof query.error === 'string';
+}