@shipfox/client-integrations 0.2.0

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

@@ -0,0 +1,238 @@
+import type {SentryConnectResponseDto} from '@shipfox/api-integration-sentry-dto';
+import {useAuthState, useRefreshAuth} from '@shipfox/client-auth';
+import {Button, ButtonLink} from '@shipfox/react-ui/button';
+import {Callout} from '@shipfox/react-ui/callout';
+import {Card} from '@shipfox/react-ui/card';
+import {FullPageLoader} from '@shipfox/react-ui/loader';
+import {toast} from '@shipfox/react-ui/toast';
+import {Header, 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 {connectSentry, integrationsQueryKeys} from '#hooks/api/integrations.js';
+import {
+  classifySentryConnectError,
+  clearSentryInstallWorkspace,
+  parseSentryCallbackParams,
+  preselectSentryWorkspace,
+  readSentryInstallWorkspace,
+  type SentryConnectFailure,
+} from '#sentry-callback.js';
+
+// De-dupes concurrent attempts for the same installation+workspace+code
+// (double click, remount while in flight). Entries are evicted once the
+// request settles, so Retry, and any later attempt carrying a fresh grant
+// code, always issues a genuinely new request instead of replaying a cached
+// outcome.
+const connectRequests = new Map<string, Promise<SentryConnectResponseDto>>();
+
+export function SentryCallbackPage() {
+  const search = useSearch({strict: false});
+  const navigate = useNavigate();
+  const refreshAuth = useRefreshAuth();
+  const {workspaces, isLoading} = useAuthState();
+  const queryClient = useQueryClient();
+
+  const params = useMemo(() => parseSentryCallbackParams(search), [search]);
+  const storedWorkspaceId = useMemo(() => readSentryInstallWorkspace(window.sessionStorage), []);
+  const preselection = preselectSentryWorkspace(storedWorkspaceId, workspaces);
+  const preselectedId = preselection.kind === 'pick' ? preselection.preselectedId : undefined;
+
+  const [connectingId, setConnectingId] = useState<string | undefined>();
+  const [failure, setFailure] = useState<
+    {workspaceId: string; failure: SentryConnectFailure} | undefined
+  >();
+  const [retryLocked, setRetryLocked] = useState(false);
+  const disposedRef = useRef(false);
+
+  useEffect(() => {
+    disposedRef.current = false;
+    return () => {
+      disposedRef.current = true;
+    };
+  }, []);
+
+  // Wait for auth before treating an empty workspace list as "no workspace": on
+  // a cold return from Sentry, `workspaces` is [] until the session refresh
+  // resolves, and bouncing to `/` then would discard the one-shot grant code.
+  const noWorkspace = !isLoading && preselection.kind === 'none';
+  useEffect(() => {
+    if (!noWorkspace) return;
+    toast.error('You need a workspace before installing Sentry.');
+    navigate({to: '/', replace: true});
+  }, [noWorkspace, navigate]);
+
+  const retryAfterSeconds =
+    failure?.failure.kind === 'retryable' ? failure.failure.retryAfterSeconds : undefined;
+  useEffect(() => {
+    // No backoff window (any non-rate-limited failure) re-enables Retry, so a
+    // prior rate-limit lock can never strand the button in a disabled state.
+    if (!retryAfterSeconds) {
+      setRetryLocked(false);
+      return;
+    }
+    setRetryLocked(true);
+    const timer = setTimeout(() => setRetryLocked(false), retryAfterSeconds * 1000);
+    return () => clearTimeout(timer);
+  }, [retryAfterSeconds]);
+
+  if (!params) {
+    return (
+      <CallbackColumn>
+        <Callout role="alert" type="error">
+          <Text size="sm">
+            This Sentry link is missing required parameters. Start the install again from your
+            workspace settings.
+          </Text>
+        </Callout>
+        <ButtonLink asChild variant="muted" className="w-fit">
+          <Link to="/">Back to Shipfox</Link>
+        </ButtonLink>
+      </CallbackColumn>
+    );
+  }
+
+  // Hold the loader until auth resolves; the workspace list and the
+  // noWorkspace redirect both depend on a settled `workspaces`.
+  if (isLoading) return <FullPageLoader />;
+
+  if (noWorkspace) return null;
+
+  const connect = (workspaceId: string) => {
+    setConnectingId(workspaceId);
+    setFailure(undefined);
+    const key = `${params.installationId}|${workspaceId}|${params.code}`;
+    let request = connectRequests.get(key);
+    if (!request) {
+      request = refreshAuth().then((session) =>
+        connectSentry({
+          body: {
+            workspace_id: workspaceId,
+            code: params.code,
+            installation_id: params.installationId,
+          },
+          token: session.token,
+        }),
+      );
+      // Evict on settle (success or failure) so the key never replays a stale
+      // outcome. Two-arg `then` keeps this cleanup branch from surfacing the
+      // rejection as unhandled — the main chain below owns the user-facing
+      // failure handling.
+      const evict = () => connectRequests.delete(key);
+      request.then(evict, evict);
+      connectRequests.set(key, request);
+    }
+
+    request
+      .then(async () => {
+        clearSentryInstallWorkspace(window.sessionStorage);
+        await queryClient.invalidateQueries({
+          queryKey: integrationsQueryKeys.connectionsByWorkspace(workspaceId),
+        });
+        if (disposedRef.current) return;
+        toast.success('Sentry installed.');
+        await navigate({
+          to: '/workspaces/$wid/settings/integrations',
+          params: {wid: workspaceId},
+          replace: true,
+        });
+      })
+      .catch((error: unknown) => {
+        if (disposedRef.current) return;
+        const classified = classifySentryConnectError(error);
+        if (classified.kind === 'terminal') {
+          // Only a fresh install (new grant code) can recover; the stored
+          // handoff has served its purpose either way.
+          clearSentryInstallWorkspace(window.sessionStorage);
+        }
+        setConnectingId(undefined);
+        setFailure({workspaceId, failure: classified});
+      });
+  };
+
+  const orderedWorkspaces = preselectedId
+    ? [
+        ...workspaces.filter((workspace) => workspace.id === preselectedId),
+        ...workspaces.filter((workspace) => workspace.id !== preselectedId),
+      ]
+    : workspaces;
+
+  const failureWorkspaceId = failure?.workspaceId ?? preselectedId ?? workspaces[0]?.id;
+
+  return (
+    <CallbackColumn>
+      <header className="flex flex-col gap-8">
+        <Header variant="h2">Install Sentry</Header>
+        <Text size="sm" className="text-foreground-neutral-muted">
+          {params.orgSlug
+            ? `Install the Sentry org "${params.orgSlug}" in a workspace.`
+            : 'Install this Sentry integration in a workspace.'}
+        </Text>
+      </header>
+
+      {failure ? (
+        <Callout role="alert" type="error">
+          <div className="flex flex-col gap-8">
+            <Text size="sm">{failure.failure.message}</Text>
+            {failure.failure.kind === 'retryable' ? (
+              <Button
+                size="sm"
+                variant="secondary"
+                className="w-fit"
+                disabled={retryLocked || connectingId !== undefined}
+                onClick={() => connect(failure.workspaceId)}
+              >
+                Retry
+              </Button>
+            ) : null}
+            {failure.failure.kind === 'terminal' && failure.failure.startOver ? (
+              <Button asChild size="sm" variant="secondary" className="w-fit">
+                <Link to="/workspaces/$wid/integrations/sentry" params={{wid: failure.workspaceId}}>
+                  Start over
+                </Link>
+              </Button>
+            ) : null}
+          </div>
+        </Callout>
+      ) : null}
+
+      <section className="flex flex-col gap-8" aria-label="Choose a workspace">
+        {orderedWorkspaces.map((workspace) => (
+          <Card key={workspace.id} className="p-16">
+            <div className="flex items-center justify-between gap-12">
+              <Text size="md" bold className="truncate">
+                {workspace.name}
+              </Text>
+              <Button
+                variant="secondary"
+                disabled={connectingId !== undefined}
+                isLoading={connectingId === workspace.id}
+                onClick={() => connect(workspace.id)}
+              >
+                Install
+              </Button>
+            </div>
+          </Card>
+        ))}
+      </section>
+
+      {failureWorkspaceId ? (
+        <ButtonLink asChild variant="muted" className="w-fit">
+          <Link to="/workspaces/$wid/settings/integrations" params={{wid: failureWorkspaceId}}>
+            Back to settings
+          </Link>
+        </ButtonLink>
+      ) : null}
+    </CallbackColumn>
+  );
+}
+
+function CallbackColumn({children}: {children: React.ReactNode}) {
+  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">
+        {children}
+      </div>
+    </main>
+  );
+}

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

@@ -0,0 +1,17 @@
+import {RedirectInstallPage} from '#components/redirect-install-page.js';
+import {createSentryInstall} from '#hooks/api/integrations.js';
+import {saveSentryInstallWorkspace} from '#sentry-callback.js';
+
+export function SentryInstallPage() {
+  return (
+    <RedirectInstallPage
+      installRequest={createSentryInstall}
+      errorFallbackMessage="Could not start Sentry install."
+      // Sentry's redirect has no state param; the stored id lets the callback
+      // pre-select this workspace. Saving never throws (see helper).
+      beforeRedirect={(workspaceId) => {
+        saveSentryInstallWorkspace(window.sessionStorage, workspaceId);
+      }}
+    />
+  );
+}

package/src/pages/source-control-onboarding-page.test.tsx

@@ -0,0 +1,46 @@
+// @vitest-environment jsdom
+import '@testing-library/jest-dom/vitest';
+import {configureApiClient} from '@shipfox/client-api';
+import {screen} from '@testing-library/react';
+import {INTEGRATIONS_TEST_WID, jsonResponse, renderIntegrationsPage} from '#test/render.js';
+import {SourceControlOnboardingPage} from './source-control-onboarding-page.js';
+
+describe('SourceControlOnboardingPage', () => {
+  test('renders only source-control provider cards', async () => {
+    const fetchImpl = vi.fn((input: RequestInfo | URL) => {
+      const url = input instanceof Request ? input.url : String(input);
+      if (url.includes('/integration-providers')) {
+        return Promise.resolve(
+          jsonResponse({
+            providers: [
+              {provider: 'github', display_name: 'GitHub', capabilities: ['source_control']},
+              {provider: 'sentry', display_name: 'Sentry', capabilities: []},
+            ],
+          }),
+        );
+      }
+      return Promise.resolve(jsonResponse({}, {status: 404}));
+    });
+    configureApiClient({baseUrl: 'https://api.example.test', fetchImpl});
+
+    renderIntegrationsPage({
+      path: `/workspaces/${INTEGRATIONS_TEST_WID}/integrations`,
+      routePath: '/workspaces/$wid/integrations',
+      element: <SourceControlOnboardingPage />,
+      extraRoutes: ['/workspaces/$wid/integrations/github'],
+    });
+
+    expect(await screen.findByRole('heading', {name: 'Install source control'})).toBeVisible();
+    expect(await screen.findByRole('link', {name: 'Install GitHub'})).toBeVisible();
+    expect(screen.queryByRole('region', {name: 'Installed integrations'})).not.toBeInTheDocument();
+    expect(screen.queryByRole('region', {name: 'Available integrations'})).not.toBeInTheDocument();
+    expect(
+      screen.queryByText('Provider accounts installed in this workspace.'),
+    ).not.toBeInTheDocument();
+
+    const urls = fetchImpl.mock.calls.map(([input]) =>
+      input instanceof Request ? input.url : String(input),
+    );
+    expect(urls.some((url) => url.includes('/integration-connections?'))).toBe(false);
+  });
+});

package/src/pages/source-control-onboarding-page.tsx

@@ -0,0 +1,26 @@
+import {useActiveWorkspace} from '@shipfox/client-auth';
+import {Header, Text} from '@shipfox/react-ui/typography';
+import {ProviderGrid} from '#components/provider-grid.js';
+import {useIntegrationProvidersQuery} from '#hooks/api/integrations.js';
+
+export function SourceControlOnboardingPage() {
+  const workspace = useActiveWorkspace();
+  const providersQuery = useIntegrationProvidersQuery({capability: 'source_control'});
+
+  return (
+    <div className="mx-auto flex w-full max-w-[640px] flex-col gap-20">
+      <header className="flex flex-col gap-8">
+        <Header variant="h1">Install source control</Header>
+        <Text size="md" className="text-foreground-neutral-muted">
+          Shipfox needs a source control integration to import your repositories.
+        </Text>
+      </header>
+
+      <ProviderGrid
+        providersQuery={providersQuery}
+        workspaceId={workspace.id}
+        emptyMessage="Enable at least one source-control provider in the application settings."
+      />
+    </div>
+  );
+}

package/src/provider-catalog.test.ts

@@ -0,0 +1,42 @@
+import {PROVIDER_CATALOG} from './provider-catalog.js';
+
+describe('PROVIDER_CATALOG', () => {
+  test('contains route entries for github, sentry, and gitea', () => {
+    expect(PROVIDER_CATALOG.github).toMatchObject({
+      kind: 'redirect-install',
+      setupPath: '/workspaces/$wid/integrations/github',
+    });
+    expect(PROVIDER_CATALOG.sentry).toMatchObject({
+      kind: 'redirect-install',
+      setupPath: '/workspaces/$wid/integrations/sentry',
+    });
+    expect(PROVIDER_CATALOG.linear).toMatchObject({
+      kind: 'redirect-install',
+      iconName: 'linear',
+      setupPath: '/workspaces/$wid/integrations/linear',
+    });
+    expect(PROVIDER_CATALOG.gitea).toMatchObject({
+      kind: 'direct-connect',
+      setupPath: '/workspaces/$wid/integrations/gitea',
+    });
+  });
+
+  test('marks providers with the install behavior their pages implement', () => {
+    expect(PROVIDER_CATALOG.github?.kind).toBe('redirect-install');
+    expect(PROVIDER_CATALOG.sentry?.kind).toBe('redirect-install');
+    expect(PROVIDER_CATALOG.linear?.kind).toBe('redirect-install');
+    expect(PROVIDER_CATALOG.gitea?.kind).toBe('direct-connect');
+    expect(PROVIDER_CATALOG.webhook?.kind).toBe('modal-connect');
+  });
+
+  test('declares webhook as a modal provider with the remixicon webhook icon', () => {
+    expect(PROVIDER_CATALOG.webhook).toEqual({
+      kind: 'modal-connect',
+      iconName: 'webhookLine',
+    });
+  });
+
+  test('returns undefined for unknown providers (gallery filter behavior)', () => {
+    expect(PROVIDER_CATALOG.gitlab).toBeUndefined();
+  });
+});

package/src/provider-catalog.ts

@@ -0,0 +1,49 @@
+import type {IconName} from '@shipfox/react-ui/icon';
+
+// Literal union (not string) so `<Link to={catalog.setupPath}>` stays typed
+// against TanStack Router's route tree.
+export type ProviderSetupPath =
+  | '/workspaces/$wid/integrations/github'
+  | '/workspaces/$wid/integrations/gitea'
+  | '/workspaces/$wid/integrations/sentry'
+  | '/workspaces/$wid/integrations/linear';
+
+interface RouteProviderCatalogEntry {
+  kind: 'redirect-install' | 'direct-connect';
+  iconName: IconName;
+  setupPath: ProviderSetupPath;
+}
+
+interface ModalProviderCatalogEntry {
+  kind: 'modal-connect';
+  iconName: IconName;
+}
+
+export type ProviderCatalogEntry = RouteProviderCatalogEntry | ModalProviderCatalogEntry;
+
+export const PROVIDER_CATALOG: Record<string, ProviderCatalogEntry> = {
+  github: {
+    kind: 'redirect-install',
+    iconName: 'github',
+    setupPath: '/workspaces/$wid/integrations/github',
+  },
+  sentry: {
+    kind: 'redirect-install',
+    iconName: 'sentry',
+    setupPath: '/workspaces/$wid/integrations/sentry',
+  },
+  linear: {
+    kind: 'redirect-install',
+    iconName: 'linear',
+    setupPath: '/workspaces/$wid/integrations/linear',
+  },
+  gitea: {
+    kind: 'direct-connect',
+    iconName: 'gitea',
+    setupPath: '/workspaces/$wid/integrations/gitea',
+  },
+  webhook: {
+    kind: 'modal-connect',
+    iconName: 'webhookLine',
+  },
+};

package/src/routes/gitea.tsx

@@ -0,0 +1,4 @@
+import {defineRoute} from '@shipfox/client-shell/runtime';
+import {GiteaInstallPage} from '#pages/gitea-install-page.js';
+
+export default defineRoute({component: GiteaInstallPage});

package/src/routes/github-callback.tsx

@@ -0,0 +1,114 @@
+import {ApiError, apiRequest} from '@shipfox/client-api';
+import {useRefreshAuth} from '@shipfox/client-auth';
+import {defineRoute} from '@shipfox/client-shell/runtime';
+import {FullPageLoader} from '@shipfox/react-ui/loader';
+import {toast} from '@shipfox/react-ui/toast';
+import {useNavigate, useSearch} from '@tanstack/react-router';
+import {useEffect} from 'react';
+
+interface GithubCallbackParams {
+  code: string;
+  installationId: number;
+  state: string;
+  setupAction?: string;
+}
+
+const callbackRequests = new Map<string, Promise<void>>();
+const toastedCallbacks = new Set<string>();
+
+export default defineRoute({component: GithubCallbackRoute});
+
+function GithubCallbackRoute() {
+  const search = useSearch({strict: false});
+  const navigate = useNavigate();
+  const refreshAuth = useRefreshAuth();
+
+  useEffect(() => {
+    const missing = missingCallbackParams(search);
+    if (missing.length > 0) {
+      toast.error(
+        `GitHub callback is missing: ${missing.join(', ')}. ${missing.includes('code') ? 'Enable "Request user authorization (OAuth) during installation" on the Shipfox GitHub App.' : ''}`,
+      );
+      navigate({to: '/', replace: true});
+      return;
+    }
+    const params = githubCallbackParams(search);
+    if (!params) {
+      toast.error('GitHub callback is missing required parameters.');
+      navigate({to: '/', replace: true});
+      return;
+    }
+    let disposed = false;
+    const key = encodeCallbackQuery(params);
+    const request =
+      callbackRequests.get(key) ??
+      refreshAuth().then(async (session) => {
+        await apiRequest(`/integrations/github/callback/api?${key}`, {
+          headers: {authorization: `Bearer ${session.token}`},
+        });
+      });
+    callbackRequests.set(key, request);
+    request
+      .then(() => {
+        if (disposed) return;
+        if (!toastedCallbacks.has(key)) {
+          toastedCallbacks.add(key);
+          toast.success('GitHub installed.');
+        }
+        navigate({to: '/', replace: true});
+      })
+      .catch((error: unknown) => {
+        if (disposed) return;
+        if (!toastedCallbacks.has(key)) {
+          toastedCallbacks.add(key);
+          toast.error(githubCallbackErrorMessage(error));
+        }
+        navigate({to: '/', replace: true});
+      });
+    return () => {
+      disposed = true;
+    };
+  }, [navigate, refreshAuth, search]);
+
+  return <FullPageLoader />;
+}
+
+function missingCallbackParams(search: Record<string, unknown>): string[] {
+  const missing: string[] = [];
+  if (!stringParam(search.code)) missing.push('code');
+  if (!numberParam(search.installation_id)) missing.push('installation_id');
+  if (!stringParam(search.state)) missing.push('state');
+  return missing;
+}
+function githubCallbackParams(search: Record<string, unknown>): GithubCallbackParams | undefined {
+  const code = stringParam(search.code);
+  const installationId = numberParam(search.installation_id);
+  const state = stringParam(search.state);
+  if (!code || installationId === undefined || !state) return undefined;
+  const setupAction = stringParam(search.setup_action);
+  return setupAction ? {code, installationId, state, setupAction} : {code, installationId, state};
+}
+function encodeCallbackQuery(params: GithubCallbackParams): string {
+  const search = new URLSearchParams();
+  search.set('code', params.code);
+  search.set('installation_id', params.installationId.toString());
+  search.set('state', params.state);
+  if (params.setupAction) search.set('setup_action', params.setupAction);
+  return search.toString();
+}
+function stringParam(value: unknown): string | undefined {
+  return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+function numberParam(value: unknown): number | undefined {
+  if (typeof value === 'number' && Number.isFinite(value)) return value;
+  if (typeof value === 'string' && value.length > 0) {
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : undefined;
+  }
+  return undefined;
+}
+function githubCallbackErrorMessage(error: unknown): string {
+  if (error instanceof ApiError) return error.message;
+  if (error instanceof Error) return error.message;
+  return 'Could not install GitHub.';
+}

package/src/routes/github.tsx

@@ -0,0 +1,4 @@
+import {defineRoute} from '@shipfox/client-shell/runtime';
+import {GithubInstallPage} from '#pages/github-install-page.js';
+
+export default defineRoute({component: GithubInstallPage});

package/src/routes/integrations.tsx

@@ -0,0 +1,4 @@
+import {defineRoute} from '@shipfox/client-shell/runtime';
+import {SourceControlOnboardingPage} from '#pages/source-control-onboarding-page.js';
+
+export default defineRoute({component: SourceControlOnboardingPage});

package/src/routes/linear-callback.tsx

@@ -0,0 +1,4 @@
+import {defineRoute} from '@shipfox/client-shell/runtime';
+import {LinearCallbackPage} from '#pages/linear-callback-page.js';
+
+export default defineRoute({component: LinearCallbackPage});

package/src/routes/linear.tsx

@@ -0,0 +1,4 @@
+import {defineRoute} from '@shipfox/client-shell/runtime';
+import {LinearInstallPage} from '#pages/linear-install-page.js';
+
+export default defineRoute({component: LinearInstallPage});

package/src/routes/sentry-callback.tsx

@@ -0,0 +1,4 @@
+import {defineRoute} from '@shipfox/client-shell/runtime';
+import {SentryCallbackPage} from '#pages/sentry-callback-page.js';
+
+export default defineRoute({component: SentryCallbackPage});

package/src/routes/sentry.tsx

@@ -0,0 +1,4 @@
+import {defineRoute} from '@shipfox/client-shell/runtime';
+import {SentryInstallPage} from '#pages/sentry-install-page.js';
+
+export default defineRoute({component: SentryInstallPage});