@shipfox/client-integrations 13.0.0 → 14.0.1

package/src/hooks/api/integration-mapper.ts

@@ -3,11 +3,13 @@ import type {
   IntegrationProviderDto,
   RepositoryDto,
 } from '@shipfox/api-integration-core-dto';
+import type {JiraAccessibleResourceDto} from '@shipfox/api-integration-jira-dto';
 import type {WebhookConnectionDto} from '@shipfox/api-integration-webhook-dto';
 import type {
   InstallRedirect,
   IntegrationConnection,
   IntegrationProvider,
+  JiraSite,
   Repository,
   WebhookConnection,
 } from '#core/models.js';
@@ -20,6 +22,10 @@ export function toInstallRedirect(dto: {install_url: string}): InstallRedirect {
   return {installUrl: dto.install_url};
 }
 
+export function toJiraSite(dto: JiraAccessibleResourceDto): JiraSite {
+  return {cloudId: dto.cloud_id, name: dto.name, url: dto.url, scopes: dto.scopes};
+}
+
 export function toIntegrationConnection(dto: IntegrationConnectionDto): IntegrationConnection {
   return {
     id: dto.id,

package/src/hooks/api/integrations.test.ts

@@ -1,8 +1,11 @@
 import type {IntegrationConnectionDto} from '@shipfox/api-integration-core-dto';
 import {configureApiClient} from '@shipfox/client-api';
 import {
+  completeJiraCallback,
+  completeJiraSiteSelection,
   completeLinearCallback,
   completeSlackCallback,
+  createJiraInstall,
   createLinearInstall,
   createSlackInstall,
   listSourceConnections,
@@ -155,3 +158,92 @@ describe('Linear transport', () => {
     );
   });
 });
+
+describe('Jira transport', () => {
+  it('posts the install workspace, maps multi-site callbacks, and completes a site selection', async () => {
+    const requests: Request[] = [];
+    const connectionBody = {
+      id: '33333333-3333-4333-8333-333333333333',
+      workspace_id: '11111111-1111-4111-8111-111111111111',
+      provider: 'jira',
+      external_account_id: 'cloud-1',
+      slug: 'jira_acme',
+      display_name: 'Jira Acme',
+      lifecycle_status: 'active',
+      capabilities: ['agent_tools'],
+      created_at: '2026-01-01T00:00:00.000Z',
+      updated_at: '2026-01-01T00:00:00.000Z',
+    };
+    configureApiClient({
+      baseUrl: 'https://api.example.test',
+      fetchImpl: vi.fn((input, init) => {
+        const request = new Request(input, init);
+        requests.push(request);
+        if (request.url.endsWith('/install'))
+          return Promise.resolve(jsonResponse({install_url: 'https://jira.example.test/install'}));
+        if (request.url.endsWith('/callback/site'))
+          return Promise.resolve(jsonResponse(connectionBody));
+        return Promise.resolve(
+          jsonResponse({
+            sites: [
+              {
+                cloud_id: 'cloud-1',
+                name: 'Acme',
+                url: 'https://acme.atlassian.net',
+                scopes: ['read:jira-work'],
+              },
+              {
+                cloud_id: 'cloud-2',
+                name: 'Beta',
+                url: 'https://beta.atlassian.net',
+                scopes: ['read:jira-work'],
+              },
+            ],
+          }),
+        );
+      }),
+    });
+
+    const install = await createJiraInstall({
+      workspace_id: '11111111-1111-4111-8111-111111111111',
+    });
+    const sites = await completeJiraCallback({
+      query: {code: 'grant code', state: 'signed state'},
+      token: 'session-token',
+    });
+    const connection = await completeJiraSiteSelection({
+      body: {cloud_id: 'cloud-1', state: 'signed state'},
+      token: 'session-token',
+    });
+
+    expect(install).toEqual({installUrl: 'https://jira.example.test/install'});
+    expect(sites).toEqual({
+      sites: [
+        {
+          cloudId: 'cloud-1',
+          name: 'Acme',
+          url: 'https://acme.atlassian.net',
+          scopes: ['read:jira-work'],
+        },
+        {
+          cloudId: 'cloud-2',
+          name: 'Beta',
+          url: 'https://beta.atlassian.net',
+          scopes: ['read:jira-work'],
+        },
+      ],
+    });
+    expect(connection.provider).toBe('jira');
+    expect(requests[0]?.url).toBe('https://api.example.test/integrations/jira/install');
+    expect(await requests[0]?.json()).toEqual({
+      workspace_id: '11111111-1111-4111-8111-111111111111',
+    });
+    expect(requests[1]?.url).toBe(
+      'https://api.example.test/integrations/jira/callback/api?code=grant+code&state=signed+state',
+    );
+    expect(requests[1]?.headers.get('authorization')).toBe('Bearer session-token');
+    expect(requests[2]?.url).toBe('https://api.example.test/integrations/jira/callback/site');
+    expect(await requests[2]?.json()).toEqual({cloud_id: 'cloud-1', state: 'signed state'});
+    expect(requests[2]?.headers.get('authorization')).toBe('Bearer session-token');
+  });
+});

package/src/hooks/api/integrations.ts

@@ -15,6 +15,15 @@ import {
   createGithubInstallResponseSchema,
   githubCallbackResponseSchema,
 } from '@shipfox/api-integration-github-dto';
+import type {
+  CompleteJiraSiteSelectionBodyDto,
+  CreateJiraInstallBodyDto,
+  JiraCallbackQueryDto,
+} from '@shipfox/api-integration-jira-dto';
+import {
+  createJiraInstallResponseSchema,
+  jiraCallbackResponseSchema,
+} from '@shipfox/api-integration-jira-dto';
 import type {
   CreateLinearInstallBodyDto,
   LinearCallbackQueryDto,
@@ -56,14 +65,17 @@ import {
   type IntegrationConnection,
   type IntegrationProvider,
   isUsableConnection,
+  type JiraSite,
   type RepositoryPage,
 } from '#core/models.js';
+import {serializeJiraCallbackQuery} from '#jira-callback.js';
 import {serializeLinearCallbackQuery} from '#linear-callback.js';
 import {serializeSlackCallbackQuery} from '#slack-callback.js';
 import {
   toInstallRedirect,
   toIntegrationConnection,
   toIntegrationProvider,
+  toJiraSite,
   toRepository,
 } from './integration-mapper.js';
 
@@ -261,6 +273,15 @@ export async function createLinearInstall(
   );
 }
 
+export async function createJiraInstall(body: CreateJiraInstallBodyDto): Promise<InstallRedirect> {
+  return toInstallRedirect(
+    await checkedApiRequest(createJiraInstallResponseSchema, '/integrations/jira/install', {
+      method: 'POST',
+      body,
+    }),
+  );
+}
+
 export async function createSlackInstall(
   body: CreateSlackInstallBodyDto,
 ): Promise<InstallRedirect> {
@@ -302,6 +323,44 @@ export async function completeSlackCallback({
   return toIntegrationConnection(response);
 }
 
+export type JiraCallbackResult = IntegrationConnection | {sites: JiraSite[]};
+
+export async function completeJiraCallback({
+  query,
+  token,
+}: {
+  query: JiraCallbackQueryDto;
+  token: string;
+}): Promise<JiraCallbackResult> {
+  const response = await checkedApiRequest(
+    jiraCallbackResponseSchema,
+    `/integrations/jira/callback/api?${serializeJiraCallbackQuery(query)}`,
+    {headers: {authorization: `Bearer ${token}`}},
+  );
+  return 'sites' in response
+    ? {sites: response.sites.map(toJiraSite)}
+    : toIntegrationConnection(response);
+}
+
+export async function completeJiraSiteSelection({
+  body,
+  token,
+}: {
+  body: CompleteJiraSiteSelectionBodyDto;
+  token: string;
+}): Promise<IntegrationConnection> {
+  const response = await checkedApiRequest(
+    integrationConnectionDtoSchema,
+    '/integrations/jira/callback/site',
+    {
+      method: 'POST',
+      body,
+      headers: {authorization: `Bearer ${token}`},
+    },
+  );
+  return toIntegrationConnection(response);
+}
+
 // Called from the callback route with an explicit bearer (same as the GitHub
 // callback): the route refreshes auth itself before forwarding the grant code.
 export async function connectSentry({body, token}: {body: SentryConnectBodyDto; token: string}) {
@@ -452,6 +511,10 @@ export function useCreateSlackInstallMutation() {
   return useMutation({mutationFn: createSlackInstall});
 }
 
+export function useCreateJiraInstallMutation() {
+  return useMutation({mutationFn: createJiraInstall});
+}
+
 export function useCompleteLinearCallbackMutation() {
   return useMutation({mutationFn: completeLinearCallback});
 }
@@ -460,6 +523,14 @@ export function useCompleteSlackCallbackMutation() {
   return useMutation({mutationFn: completeSlackCallback});
 }
 
+export function useCompleteJiraCallbackMutation() {
+  return useMutation({mutationFn: completeJiraCallback});
+}
+
+export function useCompleteJiraSiteSelectionMutation() {
+  return useMutation({mutationFn: completeJiraSiteSelection});
+}
+
 export function useUpdateIntegrationConnectionMutation() {
   const queryClient = useQueryClient();
   return useMutation({

package/src/index.ts

@@ -6,8 +6,12 @@ export * from './components/redirect-install-page.js';
 export * from './components/repository-picker.js';
 export * from './connection-status-badge.js';
 export * from './hooks/api/integrations.js';
+export * from './jira-callback.js';
+export * from './jira-form-errors.js';
 export * from './pages/gitea-install-page.js';
 export * from './pages/github-install-page.js';
+export * from './pages/jira-callback-page.js';
+export * from './pages/jira-install-page.js';
 export * from './pages/linear-callback-page.js';
 export * from './pages/linear-install-page.js';
 export * from './pages/sentry-callback-page.js';

package/src/jira-callback-state.ts

@@ -0,0 +1,19 @@
+import {createSingleFlight} from '@shipfox/client-ui';
+import type {IntegrationConnection} from '#core/models.js';
+import type {JiraCallbackResult} from '#hooks/api/integrations.js';
+
+export const JIRA_CALLBACK_CACHE_SIZE = 32;
+
+export const jiraCallbackRequests = createSingleFlight<string, JiraCallbackResult>({
+  maxTerminalResults: JIRA_CALLBACK_CACHE_SIZE,
+});
+export const jiraSiteSelectionRequests = createSingleFlight<string, IntegrationConnection>();
+export const jiraCompletedConnections = new Map<string, IntegrationConnection>();
+export const jiraToastedCallbacks = new Set<string>();
+
+export function resetJiraCallbackState(): void {
+  jiraCallbackRequests.clear();
+  jiraSiteSelectionRequests.clear();
+  jiraCompletedConnections.clear();
+  jiraToastedCallbacks.clear();
+}

package/src/jira-callback.test.ts

@@ -0,0 +1,76 @@
+import {
+  clearJiraInstallWorkspace,
+  JIRA_INSTALL_WORKSPACE_KEY,
+  parseJiraCallbackQuery,
+  readJiraInstallWorkspace,
+  saveJiraInstallWorkspace,
+  serializeJiraCallbackQuery,
+} from './jira-callback.js';
+
+describe('Jira callback helpers', () => {
+  it('parses and serializes success and provider-error callback queries', () => {
+    const success = parseJiraCallbackQuery({code: 'grant code', state: 'signed state'});
+    const providerError = parseJiraCallbackQuery({
+      error: 'access_denied',
+      error_description: 'User denied access',
+      state: 'signed state',
+    });
+
+    expect(success).toEqual({code: 'grant code', state: 'signed state'});
+    expect(providerError).toEqual({
+      error: 'access_denied',
+      error_description: 'User denied access',
+      state: 'signed state',
+    });
+    expect(success && serializeJiraCallbackQuery(success)).toBe(
+      'code=grant+code&state=signed+state',
+    );
+    expect(providerError && serializeJiraCallbackQuery(providerError)).toBe(
+      'error=access_denied&error_description=User+denied+access&state=signed+state',
+    );
+  });
+
+  it('rejects malformed callback queries and prefers a grant code', () => {
+    expect(parseJiraCallbackQuery({code: 'grant'})).toBeUndefined();
+    expect(parseJiraCallbackQuery({state: 'signed'})).toBeUndefined();
+    expect(parseJiraCallbackQuery({error: 'access_denied'})).toBeUndefined();
+    expect(parseJiraCallbackQuery({state: ['a', 'b']})).toBeUndefined();
+    expect(
+      parseJiraCallbackQuery({
+        code: 'grant',
+        error: 'access_denied',
+        state: 'signed',
+      }),
+    ).toEqual({code: 'grant', state: 'signed'});
+  });
+
+  it('round-trips workspace navigation storage and swallows storage errors', () => {
+    const storage = new Map<string, string>();
+    const workspaceStorage = {
+      getItem: (key: string) => storage.get(key) ?? null,
+      setItem: (key: string, value: string) => storage.set(key, value),
+      removeItem: (key: string) => storage.delete(key),
+    };
+
+    saveJiraInstallWorkspace(workspaceStorage, 'workspace-1');
+    expect(storage.get(JIRA_INSTALL_WORKSPACE_KEY)).toBe('workspace-1');
+    expect(readJiraInstallWorkspace(workspaceStorage)).toBe('workspace-1');
+    clearJiraInstallWorkspace(workspaceStorage);
+    expect(readJiraInstallWorkspace(workspaceStorage)).toBeUndefined();
+
+    const unavailableStorage = {
+      getItem: () => {
+        throw new Error('unavailable');
+      },
+      setItem: () => {
+        throw new Error('unavailable');
+      },
+      removeItem: () => {
+        throw new Error('unavailable');
+      },
+    };
+    expect(() => saveJiraInstallWorkspace(unavailableStorage, 'workspace-1')).not.toThrow();
+    expect(() => readJiraInstallWorkspace(unavailableStorage)).not.toThrow();
+    expect(() => clearJiraInstallWorkspace(unavailableStorage)).not.toThrow();
+  });
+});

package/src/jira-callback.ts

@@ -0,0 +1,67 @@
+import type {JiraCallbackQueryDto} from '@shipfox/api-integration-jira-dto';
+import {
+  type BrowserStorage,
+  type BrowserStorageKey,
+  createTypedBrowserStorage,
+} from '@shipfox/client-ui';
+
+export const JIRA_INSTALL_WORKSPACE_KEY = 'shipfox.jira-install.workspace-id';
+
+type WorkspaceStorage = BrowserStorage | undefined;
+
+const jiraInstallWorkspaceStorageKey = {
+  key: JIRA_INSTALL_WORKSPACE_KEY,
+  lifetime: 'session',
+  // This is a one-shot navigation hint, not private workspace state. It must
+  // remain readable on an OAuth callback before workspace hydration completes;
+  // the signed callback state and returned connection are authoritative.
+  principalScope: 'global',
+  serialize: (workspaceId: string) => workspaceId,
+  parse: (value: string) => value || undefined,
+} satisfies BrowserStorageKey<string>;
+
+export function saveJiraInstallWorkspace(storage: WorkspaceStorage, workspaceId: string): void {
+  installWorkspaceStorage(storage).write(workspaceId);
+}
+
+export function readJiraInstallWorkspace(storage: WorkspaceStorage): string | undefined {
+  return installWorkspaceStorage(storage).read();
+}
+
+export function clearJiraInstallWorkspace(storage: WorkspaceStorage): void {
+  installWorkspaceStorage(storage).remove();
+}
+
+function installWorkspaceStorage(storage: WorkspaceStorage) {
+  return createTypedBrowserStorage(() => storage, jiraInstallWorkspaceStorageKey);
+}
+
+export function parseJiraCallbackQuery(
+  search: Record<string, unknown>,
+): JiraCallbackQueryDto | undefined {
+  const state = stringParam(search.state);
+  if (!state) return undefined;
+
+  const code = stringParam(search.code);
+  if (code) return {code, state};
+
+  const error = stringParam(search.error);
+  if (!error) return undefined;
+  const errorDescription = stringParam(search.error_description);
+  return errorDescription ? {error, error_description: errorDescription, state} : {error, state};
+}
+
+export function serializeJiraCallbackQuery(query: JiraCallbackQueryDto): string {
+  const params = new URLSearchParams();
+  if ('code' in query) params.set('code', query.code);
+  else {
+    params.set('error', query.error);
+    if (query.error_description) params.set('error_description', query.error_description);
+  }
+  params.set('state', query.state);
+  return params.toString();
+}
+
+function stringParam(value: unknown): string | undefined {
+  return typeof value === 'string' && value.length > 0 ? value : undefined;
+}

package/src/jira-form-errors.test.ts

@@ -0,0 +1,57 @@
+import {ApiError} from '@shipfox/client-api';
+import {classifyJiraCallbackError} from './jira-form-errors.js';
+
+function apiError(code: string, status: number) {
+  return new ApiError({code, status, message: `${code} server message`});
+}
+
+describe('classifyJiraCallbackError', () => {
+  it.each([
+    ['invalid-jira-install-state', 'Jira install link expired', true, false],
+    ['jira-install-state-actor-mismatch', 'Different Shipfox account', true, true],
+    ['unauthorized', 'Different Shipfox account', true, true],
+    ['not-found', 'Workspace access changed', false, false],
+    ['forbidden', 'Workspace access changed', false, false],
+    ['workspace-inactive', 'Workspace access changed', false, false],
+    ['jira-installation-already-linked', 'Jira already linked', false, false],
+    ['jira-connection-already-linked', 'Jira already linked', false, false],
+    ['jira-authorization-scope-mismatch', 'Jira permissions needed', true, false],
+    ['jira-offline-access-not-granted', 'Jira permissions needed', true, false],
+    ['jira-oauth-callback-error', 'Jira permissions needed', true, false],
+    ['access-denied', 'Jira permissions needed', true, false],
+    ['jira-site-selection-mismatch', 'Jira site selection expired', true, false],
+    ['jira-pending-selection-not-found', 'Jira site selection expired', true, false],
+    ['network-error', 'Could not reach Shipfox', true, false],
+    ['rate-limited', 'Jira is temporarily unavailable', true, false],
+    ['timeout', 'Jira is temporarily unavailable', true, false],
+    ['provider-unavailable', 'Jira is temporarily unavailable', true, false],
+    ['malformed-provider-response', 'Jira is temporarily unavailable', true, false],
+    ['slug-conflict', 'Jira install could not be completed', true, false],
+  ] as const)('maps %s without surfacing the server message', (code, title, startOver, signIn) => {
+    const failure = classifyJiraCallbackError(apiError(code, 400));
+    expect(failure).toMatchObject({
+      title,
+      startOver,
+      signIn,
+    });
+    expect(failure.message).not.toContain('server message');
+  });
+
+  it('uses the generic recovery for unknown ApiError codes', () => {
+    expect(classifyJiraCallbackError(apiError('unknown-error', 400))).toEqual({
+      title: 'Jira install could not be completed',
+      message: 'Could not complete the Jira install. Start again from workspace settings.',
+      startOver: true,
+      signIn: false,
+    });
+  });
+
+  it('uses the generic recovery for unexpected errors', () => {
+    expect(classifyJiraCallbackError(new Error('network down'))).toEqual({
+      title: 'Jira install could not be completed',
+      message: 'Could not complete the Jira install. Start again from workspace settings.',
+      startOver: true,
+      signIn: false,
+    });
+  });
+});

package/src/jira-form-errors.ts

@@ -0,0 +1,94 @@
+import {ApiError} from '@shipfox/client-api';
+
+export interface JiraCallbackFailure {
+  title: string;
+  message: string;
+  startOver: boolean;
+  signIn: boolean;
+}
+
+export function classifyJiraCallbackError(error: unknown): JiraCallbackFailure {
+  if (error instanceof ApiError) {
+    switch (error.code) {
+      case 'invalid-jira-install-state':
+        return failure(
+          'Jira install link expired',
+          'Jira install link expired. Start again from workspace settings.',
+          true,
+        );
+      case 'jira-install-state-actor-mismatch':
+      case 'unauthorized':
+        return {
+          ...failure(
+            'Different Shipfox account',
+            'Different Shipfox account. Sign in with the account that started this install.',
+            true,
+          ),
+          signIn: true,
+        };
+      case 'not-found':
+      case 'forbidden':
+      case 'workspace-inactive':
+        return failure(
+          'Workspace access changed',
+          'You no longer have access to this workspace. Return to Shipfox to continue.',
+          false,
+        );
+      case 'jira-installation-already-linked':
+      case 'jira-connection-already-linked':
+        return failure(
+          'Jira already linked',
+          'This Jira site is already linked to another workspace.',
+          false,
+        );
+      case 'jira-authorization-scope-mismatch':
+      case 'jira-offline-access-not-granted':
+      case 'jira-oauth-callback-error':
+      case 'access-denied':
+        return failure(
+          'Jira permissions needed',
+          'Jira did not authorize the permissions Shipfox needs. Review the consent and start again.',
+          true,
+        );
+      case 'jira-site-selection-mismatch':
+      case 'jira-pending-selection-not-found':
+        return failure(
+          'Jira site selection expired',
+          'This Jira site selection is no longer valid. Start the install again from workspace settings.',
+          true,
+        );
+      case 'network-error':
+        return failure('Could not reach Shipfox', 'Check your connection and start again.', true);
+      case 'rate-limited':
+      case 'timeout':
+      case 'provider-unavailable':
+      case 'malformed-provider-response':
+        return failure(
+          'Jira is temporarily unavailable',
+          'Start a new install when Jira is available.',
+          true,
+        );
+      case 'slug-conflict':
+        return failure(
+          'Jira install could not be completed',
+          'Could not complete the Jira install. Start again from workspace settings.',
+          true,
+        );
+      default:
+        return fallback();
+    }
+  }
+  return fallback();
+}
+
+function failure(title: string, message: string, startOver: boolean): JiraCallbackFailure {
+  return {title, message, startOver, signIn: false};
+}
+
+function fallback(): JiraCallbackFailure {
+  return failure(
+    'Jira install could not be completed',
+    'Could not complete the Jira install. Start again from workspace settings.',
+    true,
+  );
+}

package/src/pages/gitea-install-page.tsx

@@ -40,8 +40,8 @@ export function GiteaInstallPage() {
   });
 
   return (
-    <div className="mx-auto flex w-full max-w-[480px] flex-col gap-20">
-      <header className="flex flex-col gap-8">
+    <div className="mx-auto flex w-full max-w-[480px] flex-col gap-section">
+      <header className="flex flex-col gap-inline">
         <Header variant="h1">Install Gitea</Header>
         <Text size="md" className="text-foreground-neutral-muted">
           Enter the Gitea organization to install in this workspace.
@@ -49,7 +49,7 @@ export function GiteaInstallPage() {
       </header>
 
       <form
-        className="flex flex-col gap-18"
+        className="flex flex-col gap-group"
         noValidate
         onSubmit={(event) => {
           event.preventDefault();
@@ -83,7 +83,7 @@ export function GiteaInstallPage() {
             </FormField>
           )}
         </form.Field>
-        <div className="flex items-center gap-12">
+        <div className="flex items-center gap-cluster">
           <Button type="submit" isLoading={connect.isPending}>
             Install
           </Button>