@shipfox/client-integrations 0.2.0

package/src/sentry-callback.test.ts

@@ -0,0 +1,239 @@
+import {ApiError} from '@shipfox/client-api';
+import {
+  classifySentryConnectError,
+  clearSentryInstallWorkspace,
+  parseSentryCallbackParams,
+  preselectSentryWorkspace,
+  readSentryInstallWorkspace,
+  SENTRY_INSTALL_WORKSPACE_KEY,
+  saveSentryInstallWorkspace,
+} from './sentry-callback.js';
+
+function fakeStorage(initial: Record<string, string> = {}) {
+  const map = new Map(Object.entries(initial));
+  return {
+    getItem: (key: string) => map.get(key) ?? null,
+    setItem: (key: string, value: string) => {
+      map.set(key, value);
+    },
+    removeItem: (key: string) => {
+      map.delete(key);
+    },
+    map,
+  };
+}
+
+function throwingStorage() {
+  return {
+    getItem: () => {
+      throw new Error('storage disabled');
+    },
+    setItem: () => {
+      throw new Error('storage disabled');
+    },
+    removeItem: () => {
+      throw new Error('storage disabled');
+    },
+  };
+}
+
+function apiError(params: {code: string; status: number; message?: string; details?: unknown}) {
+  return new ApiError({
+    message: params.message ?? 'failed',
+    code: params.code,
+    status: params.status,
+    details: params.details,
+  });
+}
+
+describe('parseSentryCallbackParams', () => {
+  test('parses camelCase params with display-only orgSlug', () => {
+    const params = parseSentryCallbackParams({
+      code: 'the-code',
+      installationId: 'install-1',
+      orgSlug: 'acme',
+    });
+
+    expect(params).toEqual({code: 'the-code', installationId: 'install-1', orgSlug: 'acme'});
+  });
+
+  test('accepts snake_case params defensively', () => {
+    const params = parseSentryCallbackParams({
+      code: 'the-code',
+      installation_id: 'install-1',
+      org_slug: 'acme',
+    });
+
+    expect(params).toEqual({code: 'the-code', installationId: 'install-1', orgSlug: 'acme'});
+  });
+
+  test('returns undefined when code is missing', () => {
+    const params = parseSentryCallbackParams({installationId: 'install-1'});
+
+    expect(params).toBeUndefined();
+  });
+
+  test('returns undefined when installationId is missing or empty', () => {
+    const missing = parseSentryCallbackParams({code: 'the-code'});
+    const empty = parseSentryCallbackParams({code: 'the-code', installationId: ''});
+
+    expect(missing).toBeUndefined();
+    expect(empty).toBeUndefined();
+  });
+});
+
+describe('preselectSentryWorkspace', () => {
+  const workspaces = [
+    {id: 'ws-1', name: 'One'},
+    {id: 'ws-2', name: 'Two'},
+  ];
+
+  test('pre-selects the stored workspace when it is still valid', () => {
+    const result = preselectSentryWorkspace('ws-2', workspaces);
+
+    expect(result).toEqual({kind: 'pick', preselectedId: 'ws-2'});
+  });
+
+  test('ignores a stale stored workspace id', () => {
+    const result = preselectSentryWorkspace('gone', workspaces);
+
+    expect(result).toEqual({kind: 'pick', preselectedId: undefined});
+  });
+
+  test('pre-selects a sole workspace without stored evidence', () => {
+    const result = preselectSentryWorkspace(undefined, [{id: 'ws-1', name: 'One'}]);
+
+    expect(result).toEqual({kind: 'pick', preselectedId: 'ws-1'});
+  });
+
+  test('pre-selects nothing for several workspaces without stored evidence', () => {
+    const result = preselectSentryWorkspace(undefined, workspaces);
+
+    expect(result).toEqual({kind: 'pick', preselectedId: undefined});
+  });
+
+  test('reports none when the user has no workspace', () => {
+    const result = preselectSentryWorkspace('ws-1', []);
+
+    expect(result).toEqual({kind: 'none'});
+  });
+});
+
+describe('classifySentryConnectError', () => {
+  test('409 already-linked is terminal without start-over', () => {
+    const result = classifySentryConnectError(
+      apiError({code: 'sentry-installation-already-linked', status: 409}),
+    );
+
+    expect(result).toEqual({
+      kind: 'terminal',
+      message: 'This Sentry org is already installed in another workspace.',
+      startOver: false,
+    });
+  });
+
+  test('429 rate-limited is retryable and carries retry_after_seconds', () => {
+    const result = classifySentryConnectError(
+      // Real wire shape: client-api stores the whole {code, details} body as ApiError.details.
+      apiError({
+        code: 'rate-limited',
+        status: 429,
+        details: {code: 'rate-limited', details: {retry_after_seconds: 30}},
+      }),
+    );
+
+    expect(result).toEqual({
+      kind: 'retryable',
+      message: 'Sentry is rate limiting requests. Try again in a moment.',
+      retryAfterSeconds: 30,
+    });
+  });
+
+  test('503 verification-in-progress is retryable and carries retry_after_seconds', () => {
+    const result = classifySentryConnectError(
+      apiError({
+        code: 'sentry-verification-in-progress',
+        status: 503,
+        details: {code: 'sentry-verification-in-progress', details: {retry_after_seconds: 2}},
+      }),
+    );
+
+    expect(result).toEqual({
+      kind: 'retryable',
+      message: 'Finishing Sentry verification. This only takes a moment.',
+      retryAfterSeconds: 2,
+    });
+  });
+
+  test.each(['timeout', 'provider-unavailable'])('503 %s is retryable', (code) => {
+    const result = classifySentryConnectError(apiError({code, status: 503}));
+
+    expect(result).toEqual({kind: 'retryable', message: 'Sentry is unreachable. Try again.'});
+  });
+
+  test.each([
+    'access-denied',
+    'malformed-provider-response',
+  ])('422 %s is terminal with start-over', (code) => {
+    const result = classifySentryConnectError(
+      apiError({code, status: 422, message: 'Sentry rejected the code.'}),
+    );
+
+    expect(result).toEqual({
+      kind: 'terminal',
+      message: 'Sentry rejected the code.',
+      startOver: true,
+    });
+  });
+
+  test('network failure (status 0) is retryable, not terminal', () => {
+    const result = classifySentryConnectError(apiError({code: 'network-error', status: 0}));
+
+    expect(result).toEqual({
+      kind: 'retryable',
+      message: 'Could not reach Shipfox. Check your connection and try again.',
+    });
+  });
+
+  test('5xx ApiError falls back to retryable', () => {
+    const result = classifySentryConnectError(apiError({code: 'server-error', status: 500}));
+
+    expect(result).toEqual({kind: 'retryable', message: 'Could not install Sentry. Try again.'});
+  });
+
+  test('unknown errors fall back to retryable', () => {
+    const result = classifySentryConnectError(new Error('network down'));
+
+    expect(result).toEqual({kind: 'retryable', message: 'Could not install Sentry. Try again.'});
+  });
+});
+
+describe('sentry install workspace storage helpers', () => {
+  test('round-trips the workspace id', () => {
+    const storage = fakeStorage();
+
+    saveSentryInstallWorkspace(storage, 'ws-1');
+    const read = readSentryInstallWorkspace(storage);
+
+    expect(read).toBe('ws-1');
+    expect(storage.map.get(SENTRY_INSTALL_WORKSPACE_KEY)).toBe('ws-1');
+  });
+
+  test('clear removes the key', () => {
+    const storage = fakeStorage({[SENTRY_INSTALL_WORKSPACE_KEY]: 'ws-1'});
+
+    clearSentryInstallWorkspace(storage);
+
+    expect(readSentryInstallWorkspace(storage)).toBeUndefined();
+  });
+
+  test('helpers swallow storage failures instead of throwing', () => {
+    const storage = throwingStorage();
+
+    saveSentryInstallWorkspace(storage, 'ws-1');
+    const read = readSentryInstallWorkspace(storage);
+    clearSentryInstallWorkspace(storage);
+
+    expect(read).toBeUndefined();
+  });
+});

package/src/sentry-callback.ts

@@ -0,0 +1,142 @@
+import {ApiError} from '@shipfox/client-api';
+
+export const SENTRY_INSTALL_WORKSPACE_KEY = 'shipfox.sentry-install.workspace-id';
+
+type WorkspaceStorage = Pick<Storage, 'getItem' | 'setItem' | 'removeItem'>;
+
+// 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.
+  }
+}
+
+export function readSentryInstallWorkspace(storage: WorkspaceStorage): string | undefined {
+  try {
+    return storage.getItem(SENTRY_INSTALL_WORKSPACE_KEY) ?? undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+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.
+  }
+}
+
+export interface SentryCallbackParams {
+  code: string;
+  installationId: string;
+  /** Display-only: rendered in the confirm copy, never sent to the API. */
+  orgSlug?: string | undefined;
+}
+
+export function parseSentryCallbackParams(
+  search: Record<string, unknown>,
+): SentryCallbackParams | undefined {
+  const code = stringParam(search.code);
+  // Sentry documents camelCase params; accept snake_case defensively.
+  const installationId = stringParam(search.installationId) ?? stringParam(search.installation_id);
+  if (!code || !installationId) return undefined;
+
+  const orgSlug = stringParam(search.orgSlug) ?? stringParam(search.org_slug);
+  return {code, installationId, orgSlug};
+}
+
+export interface SentryWorkspaceOption {
+  id: string;
+  name: string;
+}
+
+export type SentryWorkspacePreselection =
+  | {kind: 'pick'; preselectedId: string | undefined}
+  | {kind: 'none'};
+
+// Sentry's redirect carries no state token, so the callback can never prove it
+// belongs to an install the user started — installation always requires an
+// explicit click. The stored id (and a sole workspace) only pre-select.
+export function preselectSentryWorkspace(
+  storedId: string | undefined,
+  workspaces: SentryWorkspaceOption[],
+): SentryWorkspacePreselection {
+  if (workspaces.length === 0) return {kind: 'none'};
+  if (storedId && workspaces.some((workspace) => workspace.id === storedId)) {
+    return {kind: 'pick', preselectedId: storedId};
+  }
+  if (workspaces.length === 1) return {kind: 'pick', preselectedId: workspaces[0]?.id};
+  return {kind: 'pick', preselectedId: undefined};
+}
+
+export type SentryConnectFailure =
+  | {kind: 'retryable'; message: string; retryAfterSeconds?: number | undefined}
+  | {kind: 'terminal'; message: string; startOver: boolean};
+
+export function classifySentryConnectError(error: unknown): SentryConnectFailure {
+  if (error instanceof ApiError) {
+    if (error.code === 'sentry-installation-already-linked') {
+      return {
+        kind: 'terminal',
+        message: 'This Sentry org is already installed in another workspace.',
+        // Retrying or starting over would fail identically.
+        startOver: false,
+      };
+    }
+    if (error.code === 'sentry-verification-in-progress') {
+      // A concurrent signed webhook is still verifying the install. The grant code
+      // is untouched, so the existing backoff re-calls and finds the verified row.
+      return {
+        kind: 'retryable',
+        message: 'Finishing Sentry verification. This only takes a moment.',
+        retryAfterSeconds: retryAfterSeconds(error.details),
+      };
+    }
+    if (error.code === 'rate-limited') {
+      return {
+        kind: 'retryable',
+        message: 'Sentry is rate limiting requests. Try again in a moment.',
+        retryAfterSeconds: retryAfterSeconds(error.details),
+      };
+    }
+    if (error.code === 'timeout' || error.code === 'provider-unavailable') {
+      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
+      // 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.
+      return {
+        kind: 'retryable',
+        message: 'Could not reach Shipfox. Check your connection and try again.',
+      };
+    }
+    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: 'retryable', message: 'Could not install Sentry. Try again.'};
+}
+
+function retryAfterSeconds(details: unknown): number | undefined {
+  // client-api's toApiError stores the whole response body as ApiError.details,
+  // so the structured payload lives one level deeper at details.details (mirrors
+  // project-error.ts apiDetails()).
+  if (typeof details !== 'object' || details === null) return undefined;
+  const inner = (details as Record<string, unknown>).details;
+  if (typeof inner !== 'object' || inner === null) return undefined;
+  const value = (inner as Record<string, unknown>).retry_after_seconds;
+  return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+
+function stringParam(value: unknown): string | undefined {
+  return typeof value === 'string' && value.length > 0 ? value : undefined;
+}

package/test/render.tsx

@@ -0,0 +1,111 @@
+import {configureApiClient} from '@shipfox/client-api';
+import {type AuthState, authStateAtom} from '@shipfox/client-auth';
+import {Toaster} from '@shipfox/react-ui/toast';
+import {QueryClient, QueryClientProvider} from '@tanstack/react-query';
+import {
+  createMemoryHistory,
+  createRootRoute,
+  createRoute,
+  createRouter,
+  Outlet,
+  RouterProvider,
+} from '@tanstack/react-router';
+import {type RenderResult, render} from '@testing-library/react';
+import {Provider as JotaiProvider, useSetAtom} from 'jotai';
+import {type ReactElement, useEffect} from 'react';
+
+export const INTEGRATIONS_TEST_WID = '11111111-1111-4111-8111-111111111111';
+
+export interface TestWorkspace {
+  id: string;
+  name: string;
+  membershipId: string;
+}
+
+export function testWorkspace(overrides: Partial<TestWorkspace> = {}): TestWorkspace {
+  return {id: INTEGRATIONS_TEST_WID, name: 'Acme', membershipId: 'm-1', ...overrides};
+}
+
+export function jsonResponse(body: unknown, init: ResponseInit = {}) {
+  return new Response(JSON.stringify(body), {
+    status: 200,
+    headers: {'content-type': 'application/json'},
+    ...init,
+  });
+}
+
+function authState(workspaces: TestWorkspace[]): AuthState {
+  return {
+    status: 'authenticated',
+    token: 'token',
+    user: {
+      id: '22222222-2222-4222-8222-222222222222',
+      email: 'user@example.com',
+      name: null,
+      email_verified_at: new Date().toISOString(),
+      status: 'active',
+      created_at: new Date().toISOString(),
+      updated_at: new Date().toISOString(),
+    },
+    workspaces,
+  };
+}
+
+interface RenderIntegrationsPageOptions {
+  /** Initial history entry, may carry a query string. */
+  path: string;
+  /** Route template the element mounts at (e.g. /integrations/sentry/callback). */
+  routePath: string;
+  element: ReactElement;
+  workspaces?: TestWorkspace[];
+  /** Additional route templates registered with a stub component, for navigation targets. */
+  extraRoutes?: string[];
+  /** Seed auth as still-loading (the cold-load window) instead of authenticated. */
+  loadingAuth?: boolean;
+}
+
+function AuthSeed({workspaces, loading}: {workspaces: TestWorkspace[]; loading?: boolean}) {
+  const setAuth = useSetAtom(authStateAtom);
+
+  useEffect(() => {
+    setAuth(loading ? {status: 'loading'} : authState(workspaces));
+  }, [setAuth, workspaces, loading]);
+
+  return null;
+}
+
+export function renderIntegrationsPage(options: RenderIntegrationsPageOptions): RenderResult {
+  const workspaces = options.workspaces ?? [testWorkspace()];
+  const queryClient = new QueryClient({defaultOptions: {queries: {retry: false}}});
+
+  const rootRoute = createRootRoute({component: Outlet});
+  const mainRoute = createRoute({
+    getParentRoute: () => rootRoute,
+    path: options.routePath,
+    component: () => options.element,
+  });
+  const extraRoutes = (options.extraRoutes ?? []).map((path) =>
+    createRoute({
+      getParentRoute: () => rootRoute,
+      path,
+      component: () => <div data-testid={`route:${path}`} />,
+    }),
+  );
+
+  const router = createRouter({
+    history: createMemoryHistory({initialEntries: [options.path]}),
+    routeTree: rootRoute.addChildren([mainRoute, ...extraRoutes]),
+  });
+
+  configureApiClient({baseUrl: 'https://api.example.test'});
+
+  return render(
+    <QueryClientProvider client={queryClient}>
+      <JotaiProvider>
+        <AuthSeed workspaces={workspaces} loading={options.loadingAuth ?? false} />
+        <RouterProvider router={router} />
+        <Toaster />
+      </JotaiProvider>
+    </QueryClientProvider>,
+  );
+}

package/test/setup.ts

@@ -0,0 +1,3 @@
+import {installClientDomTestEnv} from '@shipfox/client-test-setup';
+
+installClientDomTestEnv();

package/tsconfig.build.json

@@ -0,0 +1,9 @@
+{
+  "extends": "@shipfox/ts-config/react",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist"
+  },
+  "include": ["src"],
+  "exclude": ["**/*.test.tsx", "**/*.test.ts"]
+}