@shipfox/client-integrations 0.2.0

package/src/linear-callback.test.ts

@@ -0,0 +1,227 @@
+import {ApiError} from '@shipfox/client-api';
+import {
+  classifyLinearCallbackError,
+  clearLinearInstallWorkspace,
+  LINEAR_INSTALL_WORKSPACE_KEY,
+  parseLinearCallbackQuery,
+  readLinearInstallWorkspace,
+  saveLinearInstallWorkspace,
+  serializeLinearCallbackQuery,
+} from './linear-callback.js';
+
+describe('Linear callback helpers', () => {
+  it('parses and serializes success and provider-error callback queries', () => {
+    const success = parseLinearCallbackQuery({code: 'grant code', state: 'signed state'});
+    const providerError = parseLinearCallbackQuery({
+      error: 'access_denied',
+      error_description: 'User denied access',
+      state: 'signed state',
+    });
+
+    expect(success).toEqual({code: 'grant code', state: 'signed state'});
+    expect(providerError).toEqual({
+      error: 'access_denied',
+      error_description: 'User denied access',
+      state: 'signed state',
+    });
+    expect(success && serializeLinearCallbackQuery(success)).toBe(
+      'code=grant+code&state=signed+state',
+    );
+    expect(providerError && serializeLinearCallbackQuery(providerError)).toBe(
+      'error=access_denied&error_description=User+denied+access&state=signed+state',
+    );
+  });
+
+  it('rejects malformed callback queries', () => {
+    expect(parseLinearCallbackQuery({code: 'grant'})).toBeUndefined();
+    expect(parseLinearCallbackQuery({state: 'signed'})).toBeUndefined();
+    expect(parseLinearCallbackQuery({error: 'access_denied'})).toBeUndefined();
+    expect(parseLinearCallbackQuery({state: ['a', 'b']})).toBeUndefined();
+    expect(parseLinearCallbackQuery({code: '', state: ''})).toBeUndefined();
+  });
+
+  it('prefers the grant code when a callback carries both code and error', () => {
+    const parsed = parseLinearCallbackQuery({
+      code: 'grant',
+      error: 'access_denied',
+      state: 'signed',
+    });
+
+    expect(parsed).toEqual({code: 'grant', state: 'signed'});
+  });
+
+  it('round-trips workspace navigation storage and swallows storage errors', () => {
+    const storage = new Map<string, string>();
+    const workspaceStorage = {
+      getItem: (key: string) => storage.get(key) ?? null,
+      setItem: (key: string, value: string) => storage.set(key, value),
+      removeItem: (key: string) => storage.delete(key),
+    };
+
+    saveLinearInstallWorkspace(workspaceStorage, 'workspace-1');
+    expect(storage.get(LINEAR_INSTALL_WORKSPACE_KEY)).toBe('workspace-1');
+    expect(readLinearInstallWorkspace(workspaceStorage)).toBe('workspace-1');
+    clearLinearInstallWorkspace(workspaceStorage);
+    expect(readLinearInstallWorkspace(workspaceStorage)).toBeUndefined();
+
+    const unavailableStorage = {
+      getItem: () => {
+        throw new Error('unavailable');
+      },
+      setItem: () => {
+        throw new Error('unavailable');
+      },
+      removeItem: () => {
+        throw new Error('unavailable');
+      },
+    };
+    expect(() => saveLinearInstallWorkspace(unavailableStorage, 'workspace-1')).not.toThrow();
+    expect(() => readLinearInstallWorkspace(unavailableStorage)).not.toThrow();
+    expect(() => clearLinearInstallWorkspace(unavailableStorage)).not.toThrow();
+  });
+
+  it.each([
+    [
+      'invalid-linear-install-state',
+      400,
+      {
+        title: 'Linear install link expired',
+        message: 'Linear install link expired. Start again from workspace settings.',
+        startOver: true,
+        signIn: false,
+      },
+    ],
+    [
+      'linear-install-state-actor-mismatch',
+      403,
+      {
+        title: 'Different Shipfox account',
+        message: 'Different Shipfox account. Sign in with the account that started this install.',
+        startOver: true,
+        signIn: true,
+      },
+    ],
+    [
+      'linear-installation-already-linked',
+      409,
+      {
+        title: 'Linear already linked',
+        message: 'This Linear organization is already linked to another workspace.',
+        startOver: false,
+        signIn: false,
+      },
+    ],
+    [
+      'linear-connection-already-linked',
+      409,
+      {
+        title: 'Linear already linked',
+        message: 'This Linear organization is already linked to another workspace.',
+        startOver: false,
+        signIn: false,
+      },
+    ],
+    [
+      'linear-authorization-scope-mismatch',
+      422,
+      {
+        title: 'Linear permissions needed',
+        message:
+          'Linear did not authorize the permissions Shipfox needs. Review the Linear consent and start again.',
+        startOver: true,
+        signIn: false,
+      },
+    ],
+    [
+      'linear-oauth-callback-error',
+      422,
+      {
+        title: 'Linear permissions needed',
+        message:
+          'Linear did not authorize the permissions Shipfox needs. Review the Linear consent and start again.',
+        startOver: true,
+        signIn: false,
+      },
+    ],
+    [
+      'unauthorized',
+      401,
+      {
+        title: 'Different Shipfox account',
+        message: 'Different Shipfox account. Sign in with the account that started this install.',
+        startOver: true,
+        signIn: true,
+      },
+    ],
+    [
+      'provider-unavailable',
+      503,
+      {
+        message: 'Linear is temporarily unavailable. Start a new install when it is available.',
+        startOver: true,
+        signIn: false,
+      },
+    ],
+    [
+      'timeout',
+      503,
+      {
+        message: 'Linear is temporarily unavailable. Start a new install when it is available.',
+        startOver: true,
+        signIn: false,
+      },
+    ],
+    [
+      'rate-limited',
+      429,
+      {
+        message: 'Linear is temporarily unavailable. Start a new install when it is available.',
+        startOver: true,
+        signIn: false,
+      },
+    ],
+    [
+      'network-error',
+      0,
+      {
+        message: 'Could not reach Shipfox. Check your connection and start again.',
+        startOver: true,
+        signIn: false,
+      },
+    ],
+    [
+      'slug-conflict',
+      409,
+      {
+        message: 'Could not complete the Linear install. Start again from workspace settings.',
+        startOver: true,
+        signIn: false,
+      },
+    ],
+    [
+      'unknown-error',
+      400,
+      {
+        message: 'Could not complete the Linear install. Start again from workspace settings.',
+        startOver: true,
+        signIn: false,
+      },
+    ],
+  ])('classifies %s without retrying the callback code', (code, status, expected) => {
+    const failure = classifyLinearCallbackError(
+      new ApiError({code, message: 'request failed', status}),
+    );
+
+    expect(failure).toEqual(expected);
+  });
+
+  it('uses the generic recovery for unexpected errors', () => {
+    const failure = classifyLinearCallbackError(new Error('network down'));
+
+    expect(failure).toEqual({
+      message: 'Could not complete the Linear install. Start again from workspace settings.',
+      startOver: true,
+      signIn: false,
+    });
+  });
+});

package/src/linear-callback.ts

@@ -0,0 +1,136 @@
+import type {LinearCallbackQueryDto} from '@shipfox/api-integration-linear-dto';
+import {ApiError} from '@shipfox/client-api';
+
+export const LINEAR_INSTALL_WORKSPACE_KEY = 'shipfox.linear-install.workspace-id';
+
+type WorkspaceStorage = Pick<Storage, 'getItem' | 'setItem' | 'removeItem'>;
+
+export function saveLinearInstallWorkspace(storage: WorkspaceStorage, workspaceId: string): void {
+  try {
+    storage.setItem(LINEAR_INSTALL_WORKSPACE_KEY, workspaceId);
+  } catch {
+    // Storage only improves recovery navigation; callback input always comes from the URL.
+  }
+}
+
+export function readLinearInstallWorkspace(storage: WorkspaceStorage): string | undefined {
+  try {
+    return storage.getItem(LINEAR_INSTALL_WORKSPACE_KEY) ?? undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export function clearLinearInstallWorkspace(storage: WorkspaceStorage): void {
+  try {
+    storage.removeItem(LINEAR_INSTALL_WORKSPACE_KEY);
+  } catch {
+    // A stale navigation hint cannot alter the callback request or its response.
+  }
+}
+
+export function parseLinearCallbackQuery(
+  search: Record<string, unknown>,
+): LinearCallbackQueryDto | undefined {
+  const state = stringParam(search.state);
+  if (!state) return undefined;
+
+  const code = stringParam(search.code);
+  if (code) return {code, state};
+
+  const error = stringParam(search.error);
+  if (!error) return undefined;
+  const errorDescription = stringParam(search.error_description);
+  return errorDescription ? {error, error_description: errorDescription, state} : {error, state};
+}
+
+export function serializeLinearCallbackQuery(query: LinearCallbackQueryDto): string {
+  const params = new URLSearchParams();
+  if ('code' in query) params.set('code', query.code);
+  else {
+    params.set('error', query.error);
+    if (query.error_description) params.set('error_description', query.error_description);
+  }
+  params.set('state', query.state);
+  return params.toString();
+}
+
+export type LinearCallbackFailure = {
+  title?: string;
+  message: string;
+  startOver: boolean;
+  signIn: boolean;
+};
+
+export function classifyLinearCallbackError(error: unknown): LinearCallbackFailure {
+  if (error instanceof ApiError) {
+    if (error.code === 'invalid-linear-install-state') {
+      return {
+        title: 'Linear install link expired',
+        message: 'Linear install link expired. Start again from workspace settings.',
+        startOver: true,
+        signIn: false,
+      };
+    }
+    if (error.code === 'linear-install-state-actor-mismatch' || error.code === 'unauthorized') {
+      return {
+        title: 'Different Shipfox account',
+        message: 'Different Shipfox account. Sign in with the account that started this install.',
+        startOver: true,
+        signIn: true,
+      };
+    }
+    if (
+      error.code === 'linear-installation-already-linked' ||
+      error.code === 'linear-connection-already-linked'
+    ) {
+      return {
+        title: 'Linear already linked',
+        message: 'This Linear organization is already linked to another workspace.',
+        startOver: false,
+        signIn: false,
+      };
+    }
+    if (
+      error.code === 'linear-authorization-scope-mismatch' ||
+      error.code === 'linear-oauth-callback-error'
+    ) {
+      return {
+        title: 'Linear permissions needed',
+        message:
+          'Linear did not authorize the permissions Shipfox needs. Review the Linear consent and start again.',
+        startOver: true,
+        signIn: false,
+      };
+    }
+    if (error.status === 0 || error.code === 'network-error') {
+      return {
+        message: 'Could not reach Shipfox. Check your connection and start again.',
+        startOver: true,
+        signIn: false,
+      };
+    }
+    if (
+      error.status >= 500 ||
+      error.status === 429 ||
+      error.code === 'provider-unavailable' ||
+      error.code === 'timeout' ||
+      error.code === 'rate-limited'
+    ) {
+      return {
+        message: 'Linear is temporarily unavailable. Start a new install when it is available.',
+        startOver: true,
+        signIn: false,
+      };
+    }
+  }
+  return {
+    message: 'Could not complete the Linear install. Start again from workspace settings.',
+    startOver: true,
+    signIn: false,
+  };
+}
+
+function stringParam(value: unknown): string | undefined {
+  return typeof value === 'string' && value.length > 0 ? value : undefined;
+}

package/src/pages/gitea-form-errors.test.ts

@@ -0,0 +1,55 @@
+import {ApiError} from '@shipfox/client-api';
+import {giteaConnectErrorToFormError} from './gitea-form-errors.js';
+
+function apiError(code: string, status = 400, message = `${code} server message`) {
+  return new ApiError({code, message, status});
+}
+
+describe('giteaConnectErrorToFormError', () => {
+  test('routes gitea-organization-not-found to the org field', () => {
+    const result = giteaConnectErrorToFormError(apiError('gitea-organization-not-found', 404));
+
+    expect(result).toEqual({
+      kind: 'field',
+      field: 'org',
+      message: "We couldn't find that organization on Gitea. Check the name and try again.",
+    });
+  });
+
+  test('routes gitea-org-already-linked to the org field', () => {
+    const result = giteaConnectErrorToFormError(apiError('gitea-org-already-linked', 409));
+
+    expect(result).toEqual({
+      kind: 'field',
+      field: 'org',
+      message: 'That organization is already installed.',
+    });
+  });
+
+  test('routes provider errors to a form-level alert with the server message', () => {
+    const result = giteaConnectErrorToFormError(apiError('rate-limited', 429));
+
+    expect(result).toEqual({kind: 'form', message: 'rate-limited server message'});
+  });
+
+  test('hides the raw URL in a network-error behind a friendly form-level message', () => {
+    const result = giteaConnectErrorToFormError(apiError('network-error', 0));
+
+    expect(result).toEqual({
+      kind: 'form',
+      message: "We couldn't reach the server. Check your connection and try again.",
+    });
+  });
+
+  test('routes a non-ApiError to a generic form-level alert', () => {
+    const result = giteaConnectErrorToFormError(new Error('boom'));
+
+    expect(result).toEqual({kind: 'form', message: 'boom'});
+  });
+
+  test('falls back for a non-Error value', () => {
+    const result = giteaConnectErrorToFormError('nope');
+
+    expect(result).toEqual({kind: 'form', message: 'Something went wrong. Try again.'});
+  });
+});

package/src/pages/gitea-form-errors.ts

@@ -0,0 +1,36 @@
+import {ApiError} from '@shipfox/client-api';
+
+export type GiteaConnectField = 'org';
+
+export type GiteaConnectFormErrorMapping =
+  | {kind: 'field'; field: GiteaConnectField; message: string}
+  | {kind: 'form'; message: string};
+
+export function giteaConnectErrorToFormError(error: unknown): GiteaConnectFormErrorMapping {
+  const code = error instanceof ApiError ? error.code : undefined;
+
+  if (code === 'gitea-organization-not-found') {
+    return {
+      kind: 'field',
+      field: 'org',
+      message: "We couldn't find that organization on Gitea. Check the name and try again.",
+    };
+  }
+  if (code === 'gitea-org-already-linked') {
+    return {kind: 'field', field: 'org', message: 'That organization is already installed.'};
+  }
+
+  return {kind: 'form', message: giteaConnectErrorMessage(error)};
+}
+
+function giteaConnectErrorMessage(error: unknown): string {
+  if (error instanceof ApiError) {
+    // `network-error` carries the raw request URL in its message; never surface it.
+    if (error.code === 'network-error') {
+      return "We couldn't reach the server. Check your connection and try again.";
+    }
+    return error.message;
+  }
+  if (error instanceof Error) return error.message;
+  return 'Something went wrong. Try again.';
+}

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

@@ -0,0 +1,108 @@
+import {useActiveWorkspace} from '@shipfox/client-auth';
+import {Button, ButtonLink} from '@shipfox/react-ui/button';
+import {Callout} from '@shipfox/react-ui/callout';
+import {FormField, FormFieldInput, fieldError} from '@shipfox/react-ui/form-field';
+import {toast} from '@shipfox/react-ui/toast';
+import {Header, Text} from '@shipfox/react-ui/typography';
+import {useForm} from '@tanstack/react-form';
+import {useQueryClient} from '@tanstack/react-query';
+import {Link, useNavigate} from '@tanstack/react-router';
+import {useState} from 'react';
+import {integrationsQueryKeys, useCreateGiteaConnectionMutation} from '#hooks/api/integrations.js';
+import {giteaConnectErrorToFormError} from './gitea-form-errors.js';
+
+export function GiteaInstallPage() {
+  const workspace = useActiveWorkspace();
+  const connect = useCreateGiteaConnectionMutation();
+  const queryClient = useQueryClient();
+  const navigate = useNavigate();
+  const [formError, setFormError] = useState<string | undefined>();
+
+  const form = useForm({
+    defaultValues: {org: ''},
+    onSubmit: async ({value}) => {
+      setFormError(undefined);
+      const workspaceId = workspace.id;
+      try {
+        await connect.mutateAsync({workspace_id: workspaceId, org: value.org.trim()});
+        await queryClient.invalidateQueries({
+          queryKey: integrationsQueryKeys.sourceConnections(workspaceId),
+          // The workspace home is the next active observer, not this page, so the
+          // default 'active' refetch would no-op and leave the cache stale until
+          // after the home redirects back here.
+          refetchType: 'all',
+        });
+        toast.success('Gitea organization installed.');
+        await navigate({to: '/workspaces/$wid', params: {wid: workspaceId}});
+      } catch (error) {
+        const mapped = giteaConnectErrorToFormError(error);
+        if (mapped.kind === 'field') {
+          form.setFieldMeta(mapped.field, (prev) => ({
+            ...prev,
+            errorMap: {...prev.errorMap, onServer: mapped.message},
+          }));
+        } else {
+          setFormError(mapped.message);
+        }
+      }
+    },
+  });
+
+  return (
+    <div className="mx-auto flex w-full max-w-[480px] flex-col gap-20">
+      <header className="flex flex-col gap-8">
+        <Header variant="h1">Install Gitea</Header>
+        <Text size="md" className="text-foreground-neutral-muted">
+          Enter the Gitea organization to install in this workspace.
+        </Text>
+      </header>
+
+      <form
+        className="flex flex-col gap-18"
+        noValidate
+        onSubmit={(event) => {
+          event.preventDefault();
+          event.stopPropagation();
+          void form.handleSubmit();
+        }}
+      >
+        {formError ? (
+          <Callout role="alert" type="error">
+            {formError}
+          </Callout>
+        ) : null}
+        <form.Field
+          name="org"
+          validators={{
+            onBlur: ({value}) =>
+              value.trim().length > 0 ? undefined : 'Enter your Gitea organization.',
+            onSubmit: ({value}) =>
+              value.trim().length > 0 ? undefined : 'Enter your Gitea organization.',
+          }}
+        >
+          {(field) => (
+            <FormField label="Organization" id="gitea-org" error={fieldError(field)}>
+              <FormFieldInput
+                placeholder="my-org"
+                autoComplete="off"
+                value={field.state.value}
+                onChange={(event) => field.handleChange(event.target.value)}
+                onBlur={field.handleBlur}
+              />
+            </FormField>
+          )}
+        </form.Field>
+        <div className="flex items-center gap-12">
+          <Button type="submit" isLoading={connect.isPending}>
+            Install
+          </Button>
+          <ButtonLink asChild variant="muted">
+            <Link to="/workspaces/$wid/integrations" params={{wid: workspace.id}}>
+              Cancel
+            </Link>
+          </ButtonLink>
+        </div>
+      </form>
+    </div>
+  );
+}

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

@@ -0,0 +1,11 @@
+import {RedirectInstallPage} from '#components/redirect-install-page.js';
+import {createGithubInstall} from '#hooks/api/integrations.js';
+
+export function GithubInstallPage() {
+  return (
+    <RedirectInstallPage
+      installRequest={createGithubInstall}
+      errorFallbackMessage="Could not start GitHub install."
+    />
+  );
+}