@shipfox/client-integrations 12.0.2 → 14.0.0

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

@@ -24,7 +24,7 @@ export function GiteaInstallPage() {
       try {
         await connect.mutateAsync({workspace_id: workspaceId, org: value.org.trim()});
         toast.success('Gitea organization installed.');
-        await navigate({to: '/workspaces/$wid', params: {wid: workspaceId}});
+        await navigate({to: '/w/$workspaceSlug', params: {workspaceSlug: workspace.slug}});
       } catch (error) {
         const mapped = giteaConnectErrorToFormError(error);
         if (mapped.kind === 'field') {
@@ -88,7 +88,7 @@ export function GiteaInstallPage() {
             Install
           </Button>
           <ButtonLink asChild variant="muted">
-            <Link to="/workspaces/$wid/integrations" params={{wid: workspace.id}}>
+            <Link to="/w/$workspaceSlug/integrations" params={{workspaceSlug: workspace.slug}}>
               Cancel
             </Link>
           </ButtonLink>

package/src/pages/jira-callback-page.test.tsx

@@ -0,0 +1,250 @@
+// @vitest-environment jsdom
+import '@testing-library/jest-dom/vitest';
+import {ApiError} from '@shipfox/client-api';
+import {fireEvent, screen, waitFor} from '@testing-library/react';
+import {StrictMode} from 'react';
+import {JIRA_INSTALL_WORKSPACE_KEY} from '#jira-callback.js';
+import {resetJiraCallbackState} from '#jira-callback-state.js';
+import {INTEGRATIONS_TEST_WID, renderIntegrationsPage, testWorkspace} from '#test/render.js';
+import {JiraCallbackPage} from './jira-callback-page.js';
+
+const {completeCallbackMock, completeSiteMock} = vi.hoisted(() => ({
+  completeCallbackMock: vi.fn(),
+  completeSiteMock: vi.fn(),
+}));
+
+vi.mock('@shipfox/client-auth', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('@shipfox/client-auth')>();
+  return {
+    ...actual,
+    useRefreshAuth: () => () => Promise.resolve({accessToken: 'test-token'}),
+  };
+});
+
+vi.mock('#hooks/api/integrations.js', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('#hooks/api/integrations.js')>();
+  return {
+    ...actual,
+    useCompleteJiraCallbackMutation: () => ({mutateAsync: completeCallbackMock}),
+    useCompleteJiraSiteSelectionMutation: () => ({mutateAsync: completeSiteMock}),
+  };
+});
+
+beforeEach(() => {
+  window.sessionStorage.clear();
+  resetJiraCallbackState();
+  completeCallbackMock.mockReset();
+  completeSiteMock.mockReset();
+});
+
+describe('JiraCallbackPage', () => {
+  test('lists sites from the callback and completes the selected site', async () => {
+    window.sessionStorage.setItem(JIRA_INSTALL_WORKSPACE_KEY, INTEGRATIONS_TEST_WID);
+    completeCallbackMock.mockResolvedValue({
+      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'],
+        },
+      ],
+    });
+    completeSiteMock.mockResolvedValue({
+      id: 'connection-1',
+      workspaceId: INTEGRATIONS_TEST_WID,
+      provider: 'jira',
+      externalAccountId: 'cloud-1',
+      slug: 'jira_acme',
+      displayName: 'Jira Acme',
+      lifecycleStatus: 'active',
+      capabilities: ['agent_tools'],
+      createdAt: '2026-01-01T00:00:00.000Z',
+      updatedAt: '2026-01-01T00:00:00.000Z',
+    });
+
+    const rendered = renderIntegrationsPage({
+      path: '/integrations/jira/callback?code=grant-code-jira&state=signed-state-jira',
+      routePath: '/integrations/jira/callback',
+      element: <JiraCallbackPage />,
+      workspaces: [testWorkspace()],
+      extraRoutes: [
+        '/w/acme/settings/integrations',
+        '/w/$workspaceSlug/integrations/jira',
+        '/auth/login',
+      ],
+    });
+
+    expect(await screen.findByRole('heading', {name: 'Choose a Jira site'})).toBeVisible();
+    expect(screen.getByText('Acme')).toBeVisible();
+    expect(screen.getByText('Beta')).toBeVisible();
+    expect(completeCallbackMock).toHaveBeenCalledWith({
+      query: {code: 'grant-code-jira', state: 'signed-state-jira'},
+      token: 'test-token',
+    });
+    expect(completeCallbackMock).toHaveBeenCalledTimes(1);
+
+    const connectButtons = screen.getAllByRole('button', {name: 'Connect'});
+    expect(connectButtons).toHaveLength(2);
+    fireEvent.click(connectButtons[0] as HTMLElement);
+
+    await waitFor(() =>
+      expect(completeSiteMock).toHaveBeenCalledWith({
+        body: {cloud_id: 'cloud-1', state: 'signed-state-jira'},
+        token: 'test-token',
+      }),
+    );
+    await screen.findByTestId('route:/w/acme/settings/integrations');
+    expect(completeSiteMock).toHaveBeenCalledTimes(1);
+    expect(window.sessionStorage.getItem(JIRA_INSTALL_WORKSPACE_KEY)).toBeNull();
+    expect(screen.getByText('Jira installed.')).toBeInTheDocument();
+
+    rendered.unmount();
+    renderIntegrationsPage({
+      path: '/integrations/jira/callback?code=grant-code-jira&state=signed-state-jira',
+      routePath: '/integrations/jira/callback',
+      element: <JiraCallbackPage />,
+      workspaces: [testWorkspace()],
+      extraRoutes: [
+        '/w/acme/settings/integrations',
+        '/w/$workspaceSlug/integrations/jira',
+        '/auth/login',
+      ],
+    });
+    await waitFor(() => expect(completeCallbackMock).toHaveBeenCalledTimes(1));
+    expect(await screen.findByRole('heading', {name: 'Jira connected'})).toBeVisible();
+  });
+
+  test('completes a single-site callback in Strict Mode', async () => {
+    window.sessionStorage.setItem(JIRA_INSTALL_WORKSPACE_KEY, INTEGRATIONS_TEST_WID);
+    completeCallbackMock.mockResolvedValue({
+      id: 'connection-single',
+      workspaceId: INTEGRATIONS_TEST_WID,
+      provider: 'jira',
+      externalAccountId: 'cloud-single',
+      slug: 'jira_single',
+      displayName: 'Jira Single',
+      lifecycleStatus: 'active',
+      capabilities: ['agent_tools'],
+      createdAt: '2026-01-01T00:00:00.000Z',
+      updatedAt: '2026-01-01T00:00:00.000Z',
+    });
+
+    renderIntegrationsPage({
+      path: '/integrations/jira/callback?code=grant-code-single&state=signed-state-single',
+      routePath: '/integrations/jira/callback',
+      element: (
+        <StrictMode>
+          <JiraCallbackPage />
+        </StrictMode>
+      ),
+      workspaces: [testWorkspace()],
+      extraRoutes: [
+        '/w/acme/settings/integrations',
+        '/w/$workspaceSlug/integrations/jira',
+        '/auth/login',
+      ],
+    });
+
+    await waitFor(() =>
+      expect(completeCallbackMock).toHaveBeenCalledWith({
+        query: {code: 'grant-code-single', state: 'signed-state-single'},
+        token: 'test-token',
+      }),
+    );
+    expect(completeCallbackMock).toHaveBeenCalledTimes(1);
+    await screen.findByTestId('route:/w/acme/settings/integrations');
+    expect(screen.getByText('Jira installed.')).toBeInTheDocument();
+  });
+
+  test('renders recovery without submitting an invalid callback', async () => {
+    window.sessionStorage.setItem(JIRA_INSTALL_WORKSPACE_KEY, INTEGRATIONS_TEST_WID);
+
+    renderIntegrationsPage({
+      path: '/integrations/jira/callback?state=missing-code',
+      routePath: '/integrations/jira/callback',
+      element: <JiraCallbackPage />,
+      workspaces: [testWorkspace()],
+      extraRoutes: [
+        '/w/acme/settings/integrations',
+        '/w/$workspaceSlug/integrations/jira',
+        '/auth/login',
+      ],
+    });
+
+    expect(
+      await screen.findByRole('heading', {name: 'Jira install could not be completed'}),
+    ).toBeVisible();
+    expect(completeCallbackMock).not.toHaveBeenCalled();
+    expect(screen.getByRole('link', {name: 'Start over'})).toBeVisible();
+  });
+
+  test('allows retrying a failed site selection', async () => {
+    window.sessionStorage.setItem(JIRA_INSTALL_WORKSPACE_KEY, INTEGRATIONS_TEST_WID);
+    completeCallbackMock.mockResolvedValue({
+      sites: [
+        {
+          cloudId: 'cloud-retry',
+          name: 'Retry site',
+          url: 'https://retry.atlassian.net',
+          scopes: ['read:jira-work'],
+        },
+      ],
+    });
+    completeSiteMock
+      .mockRejectedValueOnce(
+        new ApiError({
+          code: 'jira-pending-selection-not-found',
+          message: 'selection expired',
+          status: 404,
+        }),
+      )
+      .mockResolvedValueOnce({
+        id: 'connection-retry',
+        workspaceId: INTEGRATIONS_TEST_WID,
+        provider: 'jira',
+        externalAccountId: 'cloud-retry',
+        slug: 'jira_retry',
+        displayName: 'Jira Retry',
+        lifecycleStatus: 'active',
+        capabilities: ['agent_tools'],
+        createdAt: '2026-01-01T00:00:00.000Z',
+        updatedAt: '2026-01-01T00:00:00.000Z',
+      });
+
+    renderIntegrationsPage({
+      path: '/integrations/jira/callback?code=grant-code-retry&state=signed-state-retry',
+      routePath: '/integrations/jira/callback',
+      element: <JiraCallbackPage />,
+      workspaces: [testWorkspace()],
+      extraRoutes: [
+        '/w/acme/settings/integrations',
+        '/w/$workspaceSlug/integrations/jira',
+        '/auth/login',
+      ],
+    });
+
+    expect(await screen.findByRole('heading', {name: 'Choose a Jira site'})).toBeVisible();
+    const connectButton = screen.getByRole('button', {name: 'Connect'});
+    fireEvent.click(connectButton);
+
+    await waitFor(() => expect(completeSiteMock).toHaveBeenCalledTimes(1));
+    await waitFor(() => {
+      expect(screen.getByRole('alert')).toHaveTextContent(
+        'This Jira site selection is no longer valid. Start the install again from workspace settings.',
+      );
+    });
+    await waitFor(() => expect(connectButton).not.toBeDisabled());
+
+    fireEvent.click(connectButton);
+    await waitFor(() => expect(completeSiteMock).toHaveBeenCalledTimes(2));
+    await screen.findByTestId('route:/w/acme/settings/integrations');
+    expect(screen.getByText('Jira installed.')).toBeInTheDocument();
+  });
+});