@shipfox/client-integrations 5.0.0 → 6.0.2

package/src/routes/github-callback.test.ts

@@ -1,5 +1,10 @@
 import {ApiError} from '@shipfox/client-api';
-import {githubCallbackErrorMessage} from './github-callback.js';
+import {
+  githubCallbackErrorMessage,
+  githubCallbackParams,
+  missingCallbackParams,
+  validateGithubCallbackSearch,
+} from './github-callback.js';
 
 describe('githubCallbackErrorMessage', () => {
   it('does not expose an API error message or request URL', () => {
@@ -15,3 +20,32 @@ describe('githubCallbackErrorMessage', () => {
     expect(message).not.toContain('https://');
   });
 });
+
+describe('github callback route inputs', () => {
+  it('normalizes valid values and reports missing or malformed inputs', () => {
+    const search = validateGithubCallbackSearch({
+      code: 'grant-code',
+      installation_id: '42',
+      state: 'signed-state',
+      setup_action: 'install',
+    });
+
+    expect(search).toEqual({
+      code: 'grant-code',
+      installationId: 42,
+      state: 'signed-state',
+      setupAction: 'install',
+    });
+    expect(githubCallbackParams(search)).toEqual({
+      code: 'grant-code',
+      installationId: 42,
+      state: 'signed-state',
+      setupAction: 'install',
+    });
+    expect(missingCallbackParams(validateGithubCallbackSearch({code: ['bad'], state: 7}))).toEqual([
+      'code',
+      'installation_id',
+      'state',
+    ]);
+  });
+});

package/src/routes/github-callback.tsx

@@ -1,30 +1,43 @@
-import {ApiError, apiRequest} from '@shipfox/client-api';
+import {ApiError} from '@shipfox/client-api';
 import {useRefreshAuth} from '@shipfox/client-auth';
-import {defineRoute} from '@shipfox/client-shell/runtime';
+import {defineRoute, useRouteSearch} from '@shipfox/client-shell/runtime';
 import {createSingleFlight} from '@shipfox/client-ui';
 import {FullPageLoader} from '@shipfox/react-ui/loader';
 import {toast} from '@shipfox/react-ui/toast';
-import {useNavigate, useSearch} from '@tanstack/react-router';
+import {useNavigate} from '@tanstack/react-router';
 import {useEffect} from 'react';
+import {useCompleteIntegrationCallback} from '#application/complete-integration-callback.js';
+import {completeGithubCallback} from '#hooks/api/integrations.js';
 
-interface GithubCallbackParams {
+export interface GithubCallbackParams {
   code: string;
   installationId: number;
   state: string;
   setupAction?: string;
 }
 
+export interface GithubCallbackSearch {
+  code?: string;
+  installationId?: number;
+  state?: string;
+  setupAction?: string;
+}
+
 // Retain only recent completions: this bounds long-lived callback pages while
 // still covering StrictMode and immediate Back/Forward remounts.
 const callbackRequests = createSingleFlight<string, void>({maxTerminalResults: 32});
 const toastedCallbacks = new Set<string>();
 
-export default defineRoute({component: GithubCallbackRoute});
+export default defineRoute({
+  validateSearch: validateGithubCallbackSearch,
+  component: GithubCallbackRoute,
+});
 
 function GithubCallbackRoute() {
-  const search = useSearch({strict: false});
+  const search = useRouteSearch(validateGithubCallbackSearch);
   const navigate = useNavigate();
   const refreshAuth = useRefreshAuth();
+  const completeIntegrationCallback = useCompleteIntegrationCallback();
 
   useEffect(() => {
     const missing = missingCallbackParams(search);
@@ -46,11 +59,11 @@ function GithubCallbackRoute() {
     const request = callbackRequests.run(
       key,
       async () =>
-        await refreshAuth().then(async (session) => {
-          await apiRequest(`/integrations/github/callback/api?${key}`, {
-            headers: {authorization: `Bearer ${session.accessToken}`},
-          });
-        }),
+        void (await completeIntegrationCallback({
+          input: params,
+          refreshAuth,
+          complete: async (input, token) => await completeGithubCallback({...input, token}),
+        })),
     );
     request
       .then(() => {
@@ -72,24 +85,37 @@ function GithubCallbackRoute() {
     return () => {
       disposed = true;
     };
-  }, [navigate, refreshAuth, search]);
+  }, [completeIntegrationCallback, navigate, refreshAuth, search]);
 
   return <FullPageLoader />;
 }
 
-function missingCallbackParams(search: Record<string, unknown>): string[] {
+export function validateGithubCallbackSearch(input: Record<string, unknown>): GithubCallbackSearch {
+  const code = stringParam(input.code);
+  const installationId = numberParam(input.installation_id);
+  const state = stringParam(input.state);
+  const setupAction = stringParam(input.setup_action);
+  return {
+    ...(code ? {code} : {}),
+    ...(installationId === undefined ? {} : {installationId}),
+    ...(state ? {state} : {}),
+    ...(setupAction ? {setupAction} : {}),
+  };
+}
+
+export function missingCallbackParams(search: GithubCallbackSearch): 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');
+  if (!search.code) missing.push('code');
+  if (search.installationId === undefined) missing.push('installation_id');
+  if (!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);
+export function githubCallbackParams(
+  search: GithubCallbackSearch,
+): GithubCallbackParams | undefined {
+  const {code, installationId, state} = search;
   if (!code || installationId === undefined || !state) return undefined;
-  const setupAction = stringParam(search.setup_action);
+  const {setupAction} = search;
   return setupAction ? {code, installationId, state, setupAction} : {code, installationId, state};
 }
 function encodeCallbackQuery(params: GithubCallbackParams): string {

package/src/routes/linear-callback.tsx

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

package/src/routes/sentry-callback.tsx

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

package/src/routes/slack-callback.tsx

@@ -1,3 +1,8 @@
 import {defineRoute} from '@shipfox/client-shell/runtime';
 import {SlackCallbackPage} from '#pages/slack-callback-page.js';
-export default defineRoute({component: SlackCallbackPage});
+import {parseSlackCallbackQuery} from '../slack-callback.js';
+
+export default defineRoute({
+  validateSearch: parseSlackCallbackQuery,
+  component: SlackCallbackPage,
+});

package/src/sentry-callback.test.ts

@@ -181,7 +181,8 @@ describe('classifySentryConnectError', () => {
 
     expect(result).toEqual({
       kind: 'terminal',
-      message: 'Sentry rejected the code.',
+      message:
+        'Sentry did not accept this install. Start the install again from workspace settings.',
       startOver: true,
     });
   });

package/src/sentry-callback.ts

@@ -1,34 +1,41 @@
 import {ApiError} from '@shipfox/client-api';
+import {
+  type BrowserStorage,
+  type BrowserStorageKey,
+  createTypedBrowserStorage,
+} from '@shipfox/client-ui';
 
 export const SENTRY_INSTALL_WORKSPACE_KEY = 'shipfox.sentry-install.workspace-id';
 
-type WorkspaceStorage = Pick<Storage, 'getItem' | 'setItem' | 'removeItem'>;
+type WorkspaceStorage = BrowserStorage | undefined;
+
+const sentryInstallWorkspaceStorageKey = {
+  key: SENTRY_INSTALL_WORKSPACE_KEY,
+  lifetime: 'session',
+  // This is a one-shot navigation hint, not private workspace state. The
+  // callback validates it against the authenticated workspace list before use.
+  principalScope: 'global',
+  serialize: (workspaceId: string) => workspaceId,
+  parse: (value: string) => value || undefined,
+} satisfies BrowserStorageKey<string>;
 
 // Storage helpers swallow failures (quota, private mode, disabled storage):
 // the handoff is an optimization, never a requirement — the callback always
 // asks for explicit confirmation and only uses the stored id to pre-select.
 export function saveSentryInstallWorkspace(storage: WorkspaceStorage, workspaceId: string): void {
-  try {
-    storage.setItem(SENTRY_INSTALL_WORKSPACE_KEY, workspaceId);
-  } catch {
-    // The callback falls back to its sole-workspace pre-selection.
-  }
+  installWorkspaceStorage(storage).write(workspaceId);
 }
 
 export function readSentryInstallWorkspace(storage: WorkspaceStorage): string | undefined {
-  try {
-    return storage.getItem(SENTRY_INSTALL_WORKSPACE_KEY) ?? undefined;
-  } catch {
-    return undefined;
-  }
+  return installWorkspaceStorage(storage).read();
 }
 
 export function clearSentryInstallWorkspace(storage: WorkspaceStorage): void {
-  try {
-    storage.removeItem(SENTRY_INSTALL_WORKSPACE_KEY);
-  } catch {
-    // A tab-scoped leftover key is harmless: it only pre-selects.
-  }
+  installWorkspaceStorage(storage).remove();
+}
+
+function installWorkspaceStorage(storage: WorkspaceStorage) {
+  return createTypedBrowserStorage(() => storage, sentryInstallWorkspaceStorageKey);
 }
 
 export interface SentryCallbackParams {
@@ -108,7 +115,7 @@ export function classifySentryConnectError(error: unknown): SentryConnectFailure
       return {kind: 'retryable', message: 'Sentry is unreachable. Try again.'};
     }
     if (error.status === 0 || error.code === 'network-error') {
-      // A network failure (apiRequest throws status 0) never reached the
+      // A network failure (the client transport reports status 0) never reached the
       // server, so the grant code is untouched and a plain Retry can recover.
       // Must precede the status < 500 branch, which would otherwise treat it as
       // a spent code and force a full restart.
@@ -118,9 +125,12 @@ export function classifySentryConnectError(error: unknown): SentryConnectFailure
       };
     }
     if (error.status < 500) {
-      // 4xx (access-denied, malformed-provider-response, validation): the grant
-      // code is spent or rejected — only a fresh install can recover.
-      return {kind: 'terminal', message: error.message, startOver: true};
+      return {
+        kind: 'terminal',
+        message:
+          'Sentry did not accept this install. Start the install again from workspace settings.',
+        startOver: true,
+      };
     }
   }
   return {kind: 'retryable', message: 'Could not install Sentry. Try again.'};

package/src/slack-callback.ts

@@ -1,29 +1,37 @@
 import type {SlackCallbackQueryDto} from '@shipfox/api-integration-slack-dto';
 import {ApiError} from '@shipfox/client-api';
+import {
+  type BrowserStorage,
+  type BrowserStorageKey,
+  createTypedBrowserStorage,
+} from '@shipfox/client-ui';
 
 export const SLACK_INSTALL_WORKSPACE_KEY = 'shipfox.slack-install.workspace-id';
-type WorkspaceStorage = Pick<Storage, 'getItem' | 'setItem' | 'removeItem'>;
+type WorkspaceStorage = BrowserStorage | undefined;
+
+const slackInstallWorkspaceStorageKey = {
+  key: SLACK_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 callback state and returned connection are the authoritative checks.
+  principalScope: 'global',
+  serialize: (workspaceId: string) => workspaceId,
+  parse: (value: string) => value || undefined,
+} satisfies BrowserStorageKey<string>;
 
 export function saveSlackInstallWorkspace(storage: WorkspaceStorage, workspaceId: string): void {
-  try {
-    storage.setItem(SLACK_INSTALL_WORKSPACE_KEY, workspaceId);
-  } catch {
-    // Storage only supports recovery navigation.
-  }
+  installWorkspaceStorage(storage).write(workspaceId);
 }
 export function readSlackInstallWorkspace(storage: WorkspaceStorage): string | undefined {
-  try {
-    return storage.getItem(SLACK_INSTALL_WORKSPACE_KEY) ?? undefined;
-  } catch {
-    return undefined;
-  }
+  return installWorkspaceStorage(storage).read();
 }
 export function clearSlackInstallWorkspace(storage: WorkspaceStorage): void {
-  try {
-    storage.removeItem(SLACK_INSTALL_WORKSPACE_KEY);
-  } catch {
-    // A stale recovery hint cannot affect the API callback.
-  }
+  installWorkspaceStorage(storage).remove();
+}
+
+function installWorkspaceStorage(storage: WorkspaceStorage) {
+  return createTypedBrowserStorage(() => storage, slackInstallWorkspaceStorageKey);
 }
 
 export function parseSlackCallbackQuery(