@shipfox/client-integrations 0.2.0

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

@@ -0,0 +1,157 @@
+// @vitest-environment jsdom
+import '@testing-library/jest-dom/vitest';
+import {ApiError} from '@shipfox/client-api';
+import {screen, waitFor} from '@testing-library/react';
+import {StrictMode} from 'react';
+import {LINEAR_INSTALL_WORKSPACE_KEY} from '#linear-callback.js';
+import {INTEGRATIONS_TEST_WID, renderIntegrationsPage} from '#test/render.js';
+import {LinearCallbackPage} from './linear-callback-page.js';
+
+const {completeCallbackMock} = vi.hoisted(() => ({completeCallbackMock: vi.fn()}));
+
+vi.mock('@shipfox/client-auth', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('@shipfox/client-auth')>();
+  return {
+    ...actual,
+    useRefreshAuth: () => () => Promise.resolve({token: 'test-token'}),
+  };
+});
+
+vi.mock('#hooks/api/integrations.js', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('#hooks/api/integrations.js')>();
+  return {
+    ...actual,
+    useCompleteLinearCallbackMutation: () => ({mutateAsync: completeCallbackMock}),
+  };
+});
+
+function renderCallback(search: string, options?: {strict?: boolean}) {
+  return renderIntegrationsPage({
+    path: `/integrations/linear/callback${search}`,
+    routePath: '/integrations/linear/callback',
+    element: options?.strict ? (
+      <StrictMode>
+        <LinearCallbackPage />
+      </StrictMode>
+    ) : (
+      <LinearCallbackPage />
+    ),
+    extraRoutes: [
+      '/workspaces/$wid/settings/integrations',
+      '/workspaces/$wid/integrations/linear',
+      '/auth/login',
+    ],
+  });
+}
+
+beforeEach(() => {
+  window.sessionStorage.clear();
+  completeCallbackMock.mockReset();
+});
+
+describe('LinearCallbackPage', () => {
+  test('renders the recovery page without submitting malformed callbacks', async () => {
+    window.sessionStorage.setItem(LINEAR_INSTALL_WORKSPACE_KEY, INTEGRATIONS_TEST_WID);
+
+    renderCallback('?state=signed-state');
+
+    const heading = await screen.findByRole('heading', {name: 'Invalid Linear callback'});
+
+    expect(heading).toBeVisible();
+    expect(completeCallbackMock).not.toHaveBeenCalled();
+    expect(screen.getByRole('link', {name: 'Start over'})).toBeVisible();
+    expect(screen.getByRole('link', {name: 'Back to integrations'})).toBeVisible();
+    expect(document.activeElement).toBe(heading);
+    expect(heading).toHaveClass('outline-none');
+  });
+
+  test('submits a callback once in Strict Mode, clears the handoff, and navigates to the response workspace', async () => {
+    const responseWorkspaceId = '22222222-2222-4222-8222-222222222222';
+    window.sessionStorage.setItem(LINEAR_INSTALL_WORKSPACE_KEY, INTEGRATIONS_TEST_WID);
+    completeCallbackMock.mockResolvedValue({
+      id: 'connection-1',
+      workspace_id: responseWorkspaceId,
+      provider: 'linear',
+      external_account_id: 'linear-org',
+      slug: 'linear_org',
+      display_name: 'Linear org',
+      lifecycle_status: 'active',
+      capabilities: [],
+      created_at: '2026-01-01T00:00:00.000Z',
+      updated_at: '2026-01-01T00:00:00.000Z',
+    });
+
+    renderCallback('?code=grant-code-success&state=signed-state-success', {strict: true});
+
+    await waitFor(() =>
+      expect(completeCallbackMock).toHaveBeenCalledWith({
+        query: {code: 'grant-code-success', state: 'signed-state-success'},
+        token: 'test-token',
+      }),
+    );
+    expect(completeCallbackMock).toHaveBeenCalledTimes(1);
+    await waitFor(() =>
+      expect(
+        screen.getByTestId('route:/workspaces/$wid/settings/integrations'),
+      ).toBeInTheDocument(),
+    );
+    expect(window.sessionStorage.getItem(LINEAR_INSTALL_WORKSPACE_KEY)).toBeNull();
+    expect(screen.getByText('Linear installed.')).toBeInTheDocument();
+  });
+
+  test('renders terminal conflicts without offering an ineffective restart', async () => {
+    completeCallbackMock.mockRejectedValue(
+      new ApiError({
+        code: 'linear-installation-already-linked',
+        message: 'already linked',
+        status: 409,
+      }),
+    );
+
+    renderCallback('?code=grant-code-conflict&state=signed-state-conflict');
+
+    expect(await screen.findByRole('heading', {name: 'Linear already linked'})).toBeVisible();
+    expect(screen.queryByRole('link', {name: 'Start over'})).not.toBeInTheDocument();
+    expect(screen.getByRole('link', {name: 'Back to Shipfox'})).toBeVisible();
+  });
+
+  test('offers account switching and a fresh install after an actor mismatch', async () => {
+    window.sessionStorage.setItem(LINEAR_INSTALL_WORKSPACE_KEY, INTEGRATIONS_TEST_WID);
+    completeCallbackMock.mockRejectedValue(
+      new ApiError({
+        code: 'linear-install-state-actor-mismatch',
+        message: 'different account',
+        status: 403,
+      }),
+    );
+
+    renderCallback('?code=grant-code-account&state=signed-state-account');
+
+    expect(await screen.findByRole('heading', {name: 'Different Shipfox account'})).toBeVisible();
+    expect(screen.getByRole('link', {name: 'Switch account'})).toHaveAttribute(
+      'href',
+      `/auth/logout?redirect=${encodeURIComponent(
+        `/workspaces/${INTEGRATIONS_TEST_WID}/integrations/linear`,
+      )}`,
+    );
+    expect(screen.getByRole('link', {name: 'Start over'})).toBeVisible();
+  });
+
+  test('suppresses late success effects after the callback page unmounts', async () => {
+    let resolveCallback!: (value: Record<string, unknown>) => void;
+    const pendingCallback = new Promise<Record<string, unknown>>((resolve) => {
+      resolveCallback = resolve;
+    });
+    window.sessionStorage.setItem(LINEAR_INSTALL_WORKSPACE_KEY, INTEGRATIONS_TEST_WID);
+    completeCallbackMock.mockReturnValue(pendingCallback);
+
+    const callback = renderCallback('?code=grant-code-unmount&state=signed-state-unmount');
+    await waitFor(() => expect(completeCallbackMock).toHaveBeenCalledTimes(1));
+    callback.unmount();
+    resolveCallback({workspace_id: INTEGRATIONS_TEST_WID});
+    await pendingCallback;
+    await Promise.resolve();
+
+    expect(window.sessionStorage.getItem(LINEAR_INSTALL_WORKSPACE_KEY)).toBe(INTEGRATIONS_TEST_WID);
+  });
+});

package/src/pages/linear-callback-page.tsx

@@ -0,0 +1,175 @@
+import type {LinearCallbackResponseDto} from '@shipfox/api-integration-linear-dto';
+import {useRefreshAuth} from '@shipfox/client-auth';
+import {ButtonLink} from '@shipfox/react-ui/button';
+import {Callout} from '@shipfox/react-ui/callout';
+import {FullPageLoader} from '@shipfox/react-ui/loader';
+import {toast} from '@shipfox/react-ui/toast';
+import {Text} from '@shipfox/react-ui/typography';
+import {useQueryClient} from '@tanstack/react-query';
+import {Link, useNavigate, useSearch} from '@tanstack/react-router';
+import {useEffect, useMemo, useRef, useState} from 'react';
+import {integrationsQueryKeys, useCompleteLinearCallbackMutation} from '#hooks/api/integrations.js';
+import {
+  classifyLinearCallbackError,
+  clearLinearInstallWorkspace,
+  type LinearCallbackFailure,
+  parseLinearCallbackQuery,
+  readLinearInstallWorkspace,
+  serializeLinearCallbackQuery,
+} from '#linear-callback.js';
+
+// Keyed by the callback's code+state. This page has no in-place Retry (failures
+// route to "Start over", which begins a fresh install with a new state+code), so
+// entries are intentionally never evicted: retaining them dedupes StrictMode and
+// remount re-runs so the single-use grant code is exchanged at most once. The
+// sibling Sentry page evicts on settle only because its Retry replays the code.
+const callbackRequests = new Map<string, Promise<LinearCallbackResponseDto>>();
+// Keeps the success toast firing once per distinct callback even though the
+// effect re-runs against the cached request as the mutation identity churns.
+const toastedCallbacks = new Set<string>();
+
+export function LinearCallbackPage() {
+  const search = useSearch({strict: false});
+  const navigate = useNavigate();
+  const refreshAuth = useRefreshAuth();
+  const queryClient = useQueryClient();
+  const {mutateAsync: completeLinearCallback} = useCompleteLinearCallbackMutation();
+  const params = useMemo(() => parseLinearCallbackQuery(search), [search]);
+  const workspaceId = useMemo(() => {
+    try {
+      return readLinearInstallWorkspace(window.sessionStorage);
+    } catch {
+      return undefined;
+    }
+  }, []);
+  const [failure, setFailure] = useState<LinearCallbackFailure | undefined>();
+  useEffect(() => {
+    if (!params) return;
+
+    let disposed = false;
+    const key = serializeLinearCallbackQuery(params);
+    let request = callbackRequests.get(key);
+    if (!request) {
+      request = refreshAuth().then(
+        async (session) => await completeLinearCallback({query: params, token: session.token}),
+      );
+      callbackRequests.set(key, request);
+    }
+
+    request.then(
+      async (connection) => {
+        if (disposed) return;
+        try {
+          clearLinearInstallWorkspace(window.sessionStorage);
+        } catch {
+          // The successful API response remains the source of truth for navigation.
+        }
+        try {
+          await queryClient.invalidateQueries({
+            queryKey: integrationsQueryKeys.connectionsByWorkspace(connection.workspace_id),
+          });
+        } catch {
+          // Cache refresh is best effort: the successful callback is already committed server-side.
+        }
+        if (disposed) return;
+        if (!toastedCallbacks.has(key)) {
+          toastedCallbacks.add(key);
+          toast.success('Linear installed.');
+        }
+        try {
+          await navigate({
+            to: '/workspaces/$wid/settings/integrations',
+            params: {wid: connection.workspace_id},
+            replace: true,
+          });
+        } catch {
+          // Keep the completed callback page visible if client navigation is interrupted.
+        }
+      },
+      (error: unknown) => {
+        if (disposed) return;
+        setFailure(classifyLinearCallbackError(error));
+      },
+    );
+
+    return () => {
+      disposed = true;
+    };
+  }, [completeLinearCallback, navigate, params, queryClient, refreshAuth]);
+
+  if (!params) {
+    return (
+      <LinearCallbackFailurePage
+        failure={{
+          title: 'Invalid Linear callback',
+          message: 'Invalid Linear callback. Start the install again from workspace settings.',
+          startOver: true,
+          signIn: false,
+        }}
+        workspaceId={workspaceId}
+      />
+    );
+  }
+
+  if (!failure) return <FullPageLoader aria-label="Connecting Linear" />;
+
+  return <LinearCallbackFailurePage failure={failure} workspaceId={workspaceId} />;
+}
+
+function LinearCallbackFailurePage({
+  failure,
+  workspaceId,
+}: {
+  failure: LinearCallbackFailure;
+  workspaceId: string | undefined;
+}) {
+  const headingRef = useRef<HTMLHeadingElement>(null);
+
+  useEffect(() => {
+    headingRef.current?.focus();
+  }, []);
+
+  const recoveryVariant = failure.startOver || failure.signIn ? 'muted' : 'base';
+  const switchAccountHref = workspaceId
+    ? `/auth/logout?redirect=${encodeURIComponent(`/workspaces/${workspaceId}/integrations/linear`)}`
+    : '/auth/logout';
+  const settingsLink = workspaceId ? (
+    <ButtonLink asChild variant={recoveryVariant} className="min-h-44 w-full sm:w-fit">
+      <Link to="/workspaces/$wid/settings/integrations" params={{wid: workspaceId}}>
+        Back to integrations
+      </Link>
+    </ButtonLink>
+  ) : (
+    <ButtonLink asChild variant={recoveryVariant} className="min-h-44 w-full sm:w-fit">
+      <Link to="/">Back to Shipfox</Link>
+    </ButtonLink>
+  );
+
+  return (
+    <main className="flex min-h-screen bg-background-subtle-base px-16 py-32">
+      <div className="mx-auto flex w-full max-w-[480px] flex-col justify-center gap-20">
+        <h2 ref={headingRef} tabIndex={-1} className="text-24 font-semibold outline-none">
+          {failure.title ?? 'Linear install could not be completed'}
+        </h2>
+        <Callout role="alert" type="error">
+          <Text size="sm">{failure.message}</Text>
+        </Callout>
+        <div className="flex flex-col gap-8 sm:flex-row sm:items-center">
+          {failure.signIn ? (
+            <ButtonLink asChild className="min-h-44 w-full sm:w-fit">
+              <Link to={switchAccountHref}>Switch account</Link>
+            </ButtonLink>
+          ) : null}
+          {failure.startOver && workspaceId ? (
+            <ButtonLink asChild className="min-h-44 w-full sm:w-fit">
+              <Link to="/workspaces/$wid/integrations/linear" params={{wid: workspaceId}}>
+                Start over
+              </Link>
+            </ButtonLink>
+          ) : null}
+          {settingsLink}
+        </div>
+      </div>
+    </main>
+  );
+}

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

@@ -0,0 +1,26 @@
+import {useCallback} from 'react';
+import {RedirectInstallPage} from '#components/redirect-install-page.js';
+import {useCreateLinearInstallMutation} from '#hooks/api/integrations.js';
+import {saveLinearInstallWorkspace} from '#linear-callback.js';
+
+export function LinearInstallPage() {
+  const createInstall = useCreateLinearInstallMutation();
+  const installRequest = useCallback(
+    async (body: {workspace_id: string}) => await createInstall.mutateAsync(body),
+    [createInstall],
+  );
+
+  return (
+    <RedirectInstallPage
+      installRequest={installRequest}
+      errorFallbackMessage="Could not start Linear install."
+      beforeRedirect={(workspaceId) => {
+        try {
+          saveLinearInstallWorkspace(window.sessionStorage, workspaceId);
+        } catch {
+          // Storage can be disabled before the helper gets a usable Storage object.
+        }
+      }}
+    />
+  );
+}

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

@@ -0,0 +1,205 @@
+// @vitest-environment jsdom
+import '@testing-library/jest-dom/vitest';
+import {ApiError} from '@shipfox/client-api';
+import {fireEvent, screen, waitFor} from '@testing-library/react';
+import {renderIntegrationsPage, testWorkspace} from '#test/render.js';
+import {SentryCallbackPage} from './sentry-callback-page.js';
+
+const {connectSentryMock} = vi.hoisted(() => ({connectSentryMock: vi.fn()}));
+
+const MISSING_PARAMS_RE = /missing required parameters/;
+
+vi.mock('@shipfox/client-auth', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('@shipfox/client-auth')>();
+  return {
+    ...actual,
+    useRefreshAuth: () => () => Promise.resolve({token: 'test-token'}),
+  };
+});
+
+vi.mock('#hooks/api/integrations.js', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('#hooks/api/integrations.js')>();
+  return {
+    ...actual,
+    connectSentry: (...args: unknown[]) => connectSentryMock(...args) as never,
+  };
+});
+
+function renderCallback(options: {
+  installationId: string;
+  orgSlug?: string;
+  workspaces?: Parameters<typeof renderIntegrationsPage>[0]['workspaces'];
+  search?: string;
+  loadingAuth?: boolean;
+}) {
+  const search =
+    options.search ??
+    `?code=the-code&installationId=${options.installationId}${
+      options.orgSlug ? `&orgSlug=${options.orgSlug}` : ''
+    }`;
+  return renderIntegrationsPage({
+    path: `/integrations/sentry/callback${search}`,
+    routePath: '/integrations/sentry/callback',
+    element: <SentryCallbackPage />,
+    extraRoutes: ['/workspaces/$wid/settings/integrations', '/workspaces/$wid/integrations/sentry'],
+    ...(options.workspaces ? {workspaces: options.workspaces} : {}),
+    ...(options.loadingAuth ? {loadingAuth: true} : {}),
+  });
+}
+
+beforeEach(() => {
+  window.sessionStorage.clear();
+  connectSentryMock.mockReset();
+});
+
+describe('SentryCallbackPage', () => {
+  test('always asks for confirmation and never auto-installs', async () => {
+    renderCallback({installationId: 'install-confirm', orgSlug: 'acme'});
+
+    expect(await screen.findByText('Install the Sentry org "acme" in a workspace.')).toBeVisible();
+    expect(screen.getByRole('button', {name: 'Install'})).toBeVisible();
+    expect(connectSentryMock).not.toHaveBeenCalled();
+  });
+
+  test('waits for auth instead of bouncing away and discarding the grant code', async () => {
+    // On a cold return from Sentry, auth is still loading and `workspaces` is
+    // empty; the page must hold a loader, not treat that as "no workspace".
+    renderCallback({installationId: 'install-loading', loadingAuth: true});
+
+    expect(await screen.findByRole('status', {name: 'Loading'})).toBeInTheDocument();
+    expect(screen.queryByRole('button', {name: 'Install'})).not.toBeInTheDocument();
+    expect(connectSentryMock).not.toHaveBeenCalled();
+  });
+
+  test('lists every workspace when several exist', async () => {
+    renderCallback({
+      installationId: 'install-multi',
+      workspaces: [
+        testWorkspace(),
+        testWorkspace({
+          id: '33333333-3333-4333-8333-333333333333',
+          name: 'Beta',
+          membershipId: 'm-2',
+        }),
+      ],
+    });
+
+    expect(await screen.findByText('Acme')).toBeVisible();
+    expect(screen.getByText('Beta')).toBeVisible();
+    expect(screen.getAllByRole('button', {name: 'Install'})).toHaveLength(2);
+  });
+
+  test('renders a terminal state when params are missing', async () => {
+    renderCallback({installationId: 'unused', search: '?installationId=only-id'});
+
+    // Alert mounts via framer-motion (opacity 0 in jsdom), so assert presence.
+    expect(await screen.findByText(MISSING_PARAMS_RE)).toBeInTheDocument();
+    expect(screen.queryByRole('button', {name: 'Install'})).not.toBeInTheDocument();
+    expect(connectSentryMock).not.toHaveBeenCalled();
+  });
+
+  test('installs on click and lands on the settings integrations page', async () => {
+    connectSentryMock.mockResolvedValue({});
+    renderCallback({installationId: 'install-success'});
+
+    fireEvent.click(await screen.findByRole('button', {name: 'Install'}));
+
+    await screen.findByTestId('route:/workspaces/$wid/settings/integrations');
+    expect(connectSentryMock).toHaveBeenCalledWith({
+      body: {
+        workspace_id: testWorkspace().id,
+        code: 'the-code',
+        installation_id: 'install-success',
+      },
+      token: 'test-token',
+    });
+  });
+
+  test('retry after a transient failure issues a fresh request', async () => {
+    connectSentryMock
+      .mockRejectedValueOnce(
+        new ApiError({message: 'down', code: 'provider-unavailable', status: 503}),
+      )
+      .mockResolvedValueOnce({});
+    renderCallback({installationId: 'install-retry'});
+
+    fireEvent.click(await screen.findByRole('button', {name: 'Install'}));
+    fireEvent.click(await screen.findByRole('button', {name: 'Retry'}));
+
+    await screen.findByTestId('route:/workspaces/$wid/settings/integrations');
+    expect(connectSentryMock).toHaveBeenCalledTimes(2);
+  });
+
+  test('a non-rate-limited failure re-enables Retry after a rate-limit lock', async () => {
+    connectSentryMock
+      .mockRejectedValueOnce(
+        new ApiError({
+          message: 'slow down',
+          code: 'rate-limited',
+          status: 429,
+          // Real wire shape: client-api stores the whole {code, details} body as ApiError.details.
+          details: {code: 'rate-limited', details: {retry_after_seconds: 60}},
+        }),
+      )
+      .mockRejectedValueOnce(new ApiError({message: 'down', code: 'timeout', status: 503}));
+    renderCallback({installationId: 'install-lock-recover'});
+
+    // First failure is rate-limited, so the lock disables Retry.
+    fireEvent.click(await screen.findByRole('button', {name: 'Install'}));
+    await waitFor(() => expect(screen.getByRole('button', {name: 'Retry'})).toBeDisabled());
+
+    // A second attempt (via the still-enabled workspace Install) fails with no
+    // backoff hint — the lock must clear so the user is not stranded.
+    fireEvent.click(screen.getByRole('button', {name: 'Install'}));
+    await waitFor(() => expect(screen.getByRole('button', {name: 'Retry'})).toBeEnabled());
+  });
+
+  test('terminal 422 offers start-over, not retry', async () => {
+    connectSentryMock.mockRejectedValue(
+      new ApiError({message: 'Sentry rejected the code.', code: 'access-denied', status: 422}),
+    );
+    renderCallback({installationId: 'install-terminal'});
+
+    fireEvent.click(await screen.findByRole('button', {name: 'Install'}));
+
+    expect(await screen.findByText('Sentry rejected the code.')).toBeInTheDocument();
+    expect(screen.getByRole('link', {name: 'Start over'})).toBeInTheDocument();
+    expect(screen.queryByRole('button', {name: 'Retry'})).not.toBeInTheDocument();
+  });
+
+  test('409 already-linked is terminal without retry or start-over', async () => {
+    connectSentryMock.mockRejectedValue(
+      new ApiError({
+        message: 'already linked',
+        code: 'sentry-installation-already-linked',
+        status: 409,
+      }),
+    );
+    renderCallback({installationId: 'install-409'});
+
+    fireEvent.click(await screen.findByRole('button', {name: 'Install'}));
+
+    expect(
+      await screen.findByText('This Sentry org is already installed in another workspace.'),
+    ).toBeInTheDocument();
+    expect(screen.queryByRole('button', {name: 'Retry'})).not.toBeInTheDocument();
+    expect(screen.queryByRole('link', {name: 'Start over'})).not.toBeInTheDocument();
+  });
+
+  test('retry after failure works across a remount (no cached rejection)', async () => {
+    connectSentryMock.mockRejectedValue(
+      new ApiError({message: 'down', code: 'timeout', status: 503}),
+    );
+    const first = renderCallback({installationId: 'install-remount'});
+    fireEvent.click(await screen.findByRole('button', {name: 'Install'}));
+    await screen.findByRole('button', {name: 'Retry'});
+    first.unmount();
+
+    connectSentryMock.mockResolvedValue({});
+    renderCallback({installationId: 'install-remount'});
+    fireEvent.click(await screen.findByRole('button', {name: 'Install'}));
+
+    await screen.findByTestId('route:/workspaces/$wid/settings/integrations');
+    await waitFor(() => expect(connectSentryMock).toHaveBeenCalledTimes(2));
+  });
+});