@shipfox/client-integrations 0.2.0

package/src/hooks/api/integrations.ts

@@ -0,0 +1,287 @@
+import type {
+  IntegrationCapabilityDto,
+  IntegrationConnectionDto,
+  ListIntegrationConnectionsResponseDto,
+  ListIntegrationProvidersResponseDto,
+  ListRepositoriesResponseDto,
+  UpdateIntegrationConnectionBodyDto,
+} from '@shipfox/api-integration-core-dto';
+import type {
+  CreateGiteaConnectionBodyDto,
+  CreateGiteaConnectionResponseDto,
+} from '@shipfox/api-integration-gitea-dto';
+import type {
+  CreateGithubInstallBodyDto,
+  CreateGithubInstallResponseDto,
+} from '@shipfox/api-integration-github-dto';
+import type {
+  CreateLinearInstallBodyDto,
+  CreateLinearInstallResponseDto,
+  LinearCallbackQueryDto,
+  LinearCallbackResponseDto,
+} from '@shipfox/api-integration-linear-dto';
+import type {
+  CreateSentryInstallBodyDto,
+  CreateSentryInstallResponseDto,
+  SentryConnectBodyDto,
+  SentryConnectResponseDto,
+} from '@shipfox/api-integration-sentry-dto';
+import {apiRequest} from '@shipfox/client-api';
+import {useInfiniteQuery, useMutation, useQuery, useQueryClient} from '@tanstack/react-query';
+import {serializeLinearCallbackQuery} from '#linear-callback.js';
+
+export const integrationsQueryKeys = {
+  all: ['integrations'] as const,
+  providers: (capability: IntegrationCapabilityDto | 'all') =>
+    [...integrationsQueryKeys.all, 'providers', capability] as const,
+  connections: (workspaceId: string, capability: IntegrationCapabilityDto | 'all') =>
+    [...integrationsQueryKeys.all, 'connections', workspaceId, capability] as const,
+  // Prefix matching every per-capability connections query for a workspace, so
+  // a mutation can refresh all connection views without touching providers or
+  // repositories.
+  connectionsByWorkspace: (workspaceId: string) =>
+    [...integrationsQueryKeys.all, 'connections', workspaceId] as const,
+  sourceConnections: (workspaceId: string) =>
+    integrationsQueryKeys.connections(workspaceId, 'source_control'),
+  repositories: (connectionId: string, search: string) =>
+    [...integrationsQueryKeys.all, 'repositories', connectionId, search] as const,
+};
+
+export async function listIntegrationProviders({
+  capability,
+  signal,
+}: {
+  capability?: IntegrationCapabilityDto;
+  signal?: AbortSignal;
+}) {
+  const search = new URLSearchParams();
+  if (capability) search.set('capability', capability);
+  const query = search.toString();
+  const path = query ? `/integration-providers?${query}` : '/integration-providers';
+  return await apiRequest<ListIntegrationProvidersResponseDto>(path, {signal});
+}
+
+export async function listIntegrationConnections({
+  workspaceId,
+  capability,
+  signal,
+}: {
+  workspaceId: string;
+  capability?: IntegrationCapabilityDto | undefined;
+  signal?: AbortSignal | undefined;
+}) {
+  const search = new URLSearchParams({workspace_id: workspaceId});
+  if (capability) search.set('capability', capability);
+  return await apiRequest<ListIntegrationConnectionsResponseDto>(
+    `/integration-connections?${search.toString()}`,
+    {signal},
+  );
+}
+
+export async function listSourceConnections({
+  workspaceId,
+  signal,
+}: {
+  workspaceId: string;
+  signal?: AbortSignal;
+}) {
+  const result = await listIntegrationConnections({
+    workspaceId,
+    capability: 'source_control',
+    signal,
+  });
+  // The endpoint returns every lifecycle status (the settings hub needs that),
+  // but source-control consumers (onboarding redirect, project creation) only
+  // act on usable connections — a disabled/error one must read as "not there".
+  return {
+    ...result,
+    connections: result.connections.filter(
+      (connection) => connection.lifecycle_status === 'active',
+    ),
+  };
+}
+
+export async function createGiteaConnection(body: CreateGiteaConnectionBodyDto) {
+  return await apiRequest<CreateGiteaConnectionResponseDto>('/integrations/gitea/connections', {
+    method: 'POST',
+    body,
+  });
+}
+
+export async function createGithubInstall(body: CreateGithubInstallBodyDto) {
+  return await apiRequest<CreateGithubInstallResponseDto>('/integrations/github/install', {
+    method: 'POST',
+    body,
+  });
+}
+
+export async function createSentryInstall(body: CreateSentryInstallBodyDto) {
+  return await apiRequest<CreateSentryInstallResponseDto>('/integrations/sentry/install', {
+    method: 'POST',
+    body,
+  });
+}
+
+export async function createLinearInstall(body: CreateLinearInstallBodyDto) {
+  return await apiRequest<CreateLinearInstallResponseDto>('/integrations/linear/install', {
+    method: 'POST',
+    body,
+  });
+}
+
+export async function completeLinearCallback({
+  query,
+  token,
+}: {
+  query: LinearCallbackQueryDto;
+  token: string;
+}) {
+  return await apiRequest<LinearCallbackResponseDto>(
+    `/integrations/linear/callback/api?${serializeLinearCallbackQuery(query)}`,
+    {headers: {authorization: `Bearer ${token}`}},
+  );
+}
+
+// Called from the callback route with an explicit bearer (same as the GitHub
+// callback): the route refreshes auth itself before forwarding the grant code.
+export async function connectSentry({body, token}: {body: SentryConnectBodyDto; token: string}) {
+  return await apiRequest<SentryConnectResponseDto>('/integrations/sentry/connect', {
+    method: 'POST',
+    body,
+    headers: {authorization: `Bearer ${token}`},
+  });
+}
+
+export async function listRepositories({
+  connectionId,
+  cursor,
+  search,
+  signal,
+}: {
+  connectionId: string;
+  cursor?: string;
+  search?: string;
+  signal?: AbortSignal;
+}) {
+  const params = new URLSearchParams();
+  if (cursor) params.set('cursor', cursor);
+  if (search) params.set('search', search);
+  const query = params.toString();
+  const path = query
+    ? `/integration-connections/${connectionId}/repositories?${query}`
+    : `/integration-connections/${connectionId}/repositories`;
+  return await apiRequest<ListRepositoriesResponseDto>(path, {signal});
+}
+
+export async function updateIntegrationConnection({
+  connectionId,
+  body,
+}: {
+  connectionId: string;
+  body: UpdateIntegrationConnectionBodyDto;
+}) {
+  return await apiRequest<IntegrationConnectionDto>(
+    `/integration-connections/${encodeURIComponent(connectionId)}`,
+    {method: 'PATCH', body},
+  );
+}
+
+export async function deleteIntegrationConnection({connectionId}: {connectionId: string}) {
+  await apiRequest<void>(`/integration-connections/${encodeURIComponent(connectionId)}`, {
+    method: 'DELETE',
+  });
+}
+
+export function useIntegrationProvidersQuery(params?: {capability?: IntegrationCapabilityDto}) {
+  const capability = params?.capability;
+  return useQuery({
+    queryKey: integrationsQueryKeys.providers(capability ?? 'all'),
+    queryFn: ({signal}) => listIntegrationProviders(capability ? {capability, signal} : {signal}),
+  });
+}
+
+export function useSourceConnectionsQuery(workspaceId: string | undefined) {
+  return useQuery({
+    queryKey: workspaceId
+      ? integrationsQueryKeys.sourceConnections(workspaceId)
+      : [...integrationsQueryKeys.all, 'source-connections'],
+    enabled: Boolean(workspaceId),
+    queryFn: ({signal}) => listSourceConnections({workspaceId: workspaceId ?? '', signal}),
+  });
+}
+
+export function useIntegrationConnectionsQuery(workspaceId: string | undefined) {
+  return useQuery({
+    queryKey: workspaceId
+      ? integrationsQueryKeys.connections(workspaceId, 'all')
+      : [...integrationsQueryKeys.all, 'connections'],
+    enabled: Boolean(workspaceId),
+    queryFn: ({signal}) => listIntegrationConnections({workspaceId: workspaceId ?? '', signal}),
+  });
+}
+
+export function useRepositoriesInfiniteQuery(
+  connectionId: string | undefined,
+  options?: {search?: string},
+) {
+  const trimmedSearch = options?.search?.trim() ?? '';
+  return useInfiniteQuery({
+    queryKey: connectionId
+      ? integrationsQueryKeys.repositories(connectionId, trimmedSearch)
+      : [...integrationsQueryKeys.all, 'repositories'],
+    enabled: Boolean(connectionId),
+    initialPageParam: undefined as string | undefined,
+    queryFn: ({pageParam, signal}) => {
+      const args: {connectionId: string; cursor?: string; search?: string; signal: AbortSignal} = {
+        connectionId: connectionId ?? '',
+        signal,
+      };
+      if (pageParam) args.cursor = pageParam;
+      if (trimmedSearch) args.search = trimmedSearch;
+      return listRepositories(args);
+    },
+    getNextPageParam: (lastPage) => lastPage.next_cursor ?? undefined,
+  });
+}
+
+export function useCreateGiteaConnectionMutation() {
+  return useMutation({mutationFn: createGiteaConnection});
+}
+
+export function useCreateLinearInstallMutation() {
+  return useMutation({mutationFn: createLinearInstall});
+}
+
+export function useCompleteLinearCallbackMutation() {
+  return useMutation({mutationFn: completeLinearCallback});
+}
+
+export function useUpdateIntegrationConnectionMutation() {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: updateIntegrationConnection,
+    onSuccess: async (connection) => {
+      await queryClient.invalidateQueries({
+        queryKey: integrationsQueryKeys.connectionsByWorkspace(connection.workspace_id),
+      });
+    },
+  });
+}
+
+export function useDeleteIntegrationConnectionMutation() {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: ({
+      workspaceId: _workspaceId,
+      connectionId,
+    }: {
+      workspaceId: string;
+      connectionId: string;
+    }) => deleteIntegrationConnection({connectionId}),
+    onSuccess: async (_result, variables) => {
+      await queryClient.invalidateQueries({
+        queryKey: integrationsQueryKeys.connectionsByWorkspace(variables.workspaceId),
+      });
+    },
+  });
+}

package/src/hooks/api/webhook-connections.ts

@@ -0,0 +1,115 @@
+import type {
+  CreateWebhookConnectionBodyDto,
+  ListWebhookConnectionsResponseDto,
+  UpdateWebhookConnectionBodyDto,
+  WebhookConnectionDto,
+} from '@shipfox/api-integration-webhook-dto';
+import {apiRequest} from '@shipfox/client-api';
+import {type QueryClient, useMutation, useQuery, useQueryClient} from '@tanstack/react-query';
+import {integrationsQueryKeys} from './integrations.js';
+
+export const webhookConnectionsQueryKeys = {
+  all: ['webhook-connections'] as const,
+  list: (workspaceId: string) => [...webhookConnectionsQueryKeys.all, 'list', workspaceId] as const,
+};
+
+export async function listWebhookConnections({
+  workspaceId,
+  signal,
+}: {
+  workspaceId: string;
+  signal?: AbortSignal;
+}) {
+  const search = new URLSearchParams({workspace_id: workspaceId});
+  return await apiRequest<ListWebhookConnectionsResponseDto>(
+    `/integrations/webhook/connections?${search.toString()}`,
+    {signal},
+  );
+}
+
+export async function createWebhookConnection(body: CreateWebhookConnectionBodyDto) {
+  return await apiRequest<WebhookConnectionDto>('/integrations/webhook/connections', {
+    method: 'POST',
+    body,
+  });
+}
+
+export async function updateWebhookConnection({
+  connectionId,
+  body,
+}: {
+  connectionId: string;
+  body: UpdateWebhookConnectionBodyDto;
+}) {
+  return await apiRequest<WebhookConnectionDto>(
+    `/integrations/webhook/connections/${encodeURIComponent(connectionId)}`,
+    {method: 'PATCH', body},
+  );
+}
+
+export async function deleteWebhookConnection({connectionId}: {connectionId: string}) {
+  await apiRequest<void>(`/integrations/webhook/connections/${encodeURIComponent(connectionId)}`, {
+    method: 'DELETE',
+  });
+}
+
+export function useWebhookConnectionsQuery(workspaceId: string | undefined) {
+  return useQuery({
+    queryKey: workspaceId
+      ? webhookConnectionsQueryKeys.list(workspaceId)
+      : [...webhookConnectionsQueryKeys.all, 'list'],
+    enabled: Boolean(workspaceId),
+    queryFn: ({signal}) => listWebhookConnections({workspaceId: workspaceId ?? '', signal}),
+  });
+}
+
+export function useCreateWebhookConnectionMutation() {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: createWebhookConnection,
+    onSuccess: async (connection) => {
+      await invalidateWebhookConnectionViews(queryClient, connection.workspace_id);
+    },
+  });
+}
+
+export function useUpdateWebhookConnectionMutation() {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: ({
+      connectionId,
+      body,
+    }: {
+      workspaceId: string;
+      connectionId: string;
+      body: UpdateWebhookConnectionBodyDto;
+    }) => updateWebhookConnection({connectionId, body}),
+    onSuccess: async (connection) => {
+      await invalidateWebhookConnectionViews(queryClient, connection.workspace_id);
+    },
+  });
+}
+
+export function useDeleteWebhookConnectionMutation() {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: ({connectionId}: {workspaceId: string; connectionId: string}) =>
+      deleteWebhookConnection({connectionId}),
+    onSuccess: async (_result, variables) => {
+      await invalidateWebhookConnectionViews(queryClient, variables.workspaceId);
+    },
+  });
+}
+
+async function invalidateWebhookConnectionViews(queryClient: QueryClient, workspaceId: string) {
+  await Promise.all([
+    queryClient.invalidateQueries({
+      queryKey: webhookConnectionsQueryKeys.list(workspaceId),
+      refetchType: 'all',
+    }),
+    queryClient.invalidateQueries({
+      queryKey: integrationsQueryKeys.connectionsByWorkspace(workspaceId),
+      refetchType: 'all',
+    }),
+  ]);
+}

package/src/index.ts

@@ -0,0 +1,16 @@
+export * from './components/connection-picker.js';
+export * from './components/integration-gallery.js';
+export * from './components/redirect-install-page.js';
+export * from './components/repository-picker.js';
+export * from './connection-status-badge.js';
+export * from './hooks/api/integrations.js';
+export * from './integration-icon.js';
+export * from './pages/gitea-install-page.js';
+export * from './pages/github-install-page.js';
+export * from './pages/linear-callback-page.js';
+export * from './pages/linear-install-page.js';
+export * from './pages/sentry-callback-page.js';
+export * from './pages/sentry-install-page.js';
+export * from './pages/source-control-onboarding-page.js';
+export * from './provider-catalog.js';
+export * from './sentry-callback.js';

package/src/integration-icon.react.test.tsx

@@ -0,0 +1,40 @@
+// @vitest-environment jsdom
+import '@testing-library/jest-dom/vitest';
+import {render} from '@testing-library/react';
+import {IntegrationIcon} from './integration-icon.js';
+
+describe('IntegrationIcon', () => {
+  it('exposes a labeled icon to assistive tech when it is the sole identifier', () => {
+    const {container} = render(<IntegrationIcon source="github" aria-label="GitHub" />);
+
+    const svg = container.querySelector('svg');
+    expect(svg).toHaveAttribute('aria-label', 'GitHub');
+    expect(svg).not.toHaveAttribute('aria-hidden');
+  });
+
+  it('hides the icon from assistive tech when marked decorative', () => {
+    const {container} = render(<IntegrationIcon source="github" aria-hidden />);
+
+    const svg = container.querySelector('svg');
+    expect(svg).toHaveAttribute('aria-hidden', 'true');
+  });
+
+  it('forwards class names so callers control sizing and color', () => {
+    const {container} = render(
+      <IntegrationIcon source="github" className="size-24 text-foreground-neutral-base" />,
+    );
+
+    const svg = container.querySelector('svg');
+    expect(svg).toHaveClass('size-24', 'text-foreground-neutral-base');
+  });
+
+  it('forwards sizing and label to the neutral fallback glyph for an unknown source', () => {
+    const {container} = render(
+      <IntegrationIcon source="gitlab" aria-label="GitLab" className="size-24" />,
+    );
+
+    const svg = container.querySelector('svg');
+    expect(svg).toHaveAttribute('aria-label', 'GitLab');
+    expect(svg).toHaveClass('size-24');
+  });
+});

package/src/integration-icon.test.ts

@@ -0,0 +1,19 @@
+import {FALLBACK_INTEGRATION_ICON, getIntegrationIcon} from './integration-icon.js';
+
+describe('getIntegrationIcon', () => {
+  it('resolves cataloged providers to the icon they declare', () => {
+    expect(getIntegrationIcon('github')).toBe('github');
+    expect(getIntegrationIcon('sentry')).toBe('sentry');
+    expect(getIntegrationIcon('linear')).toBe('linear');
+    expect(getIntegrationIcon('gitea')).toBe('gitea');
+  });
+
+  it('falls back for sources missing from the catalog', () => {
+    expect(getIntegrationIcon('gitlab')).toBe(FALLBACK_INTEGRATION_ICON);
+    expect(getIntegrationIcon('mystery')).toBe(FALLBACK_INTEGRATION_ICON);
+  });
+
+  it.each([['' as const], [null], [undefined]])('falls back for an empty source (%s)', (source) => {
+    expect(getIntegrationIcon(source)).toBe(FALLBACK_INTEGRATION_ICON);
+  });
+});

package/src/integration-icon.tsx

@@ -0,0 +1,26 @@
+import {Icon, type IconName} from '@shipfox/react-ui/icon';
+import type {ComponentProps} from 'react';
+import {PROVIDER_CATALOG} from '#provider-catalog.js';
+
+export const FALLBACK_INTEGRATION_ICON: IconName = 'componentLine';
+
+/**
+ * Accepts the source strings used by connections and events; unknown values use
+ * the neutral fallback icon.
+ */
+export function getIntegrationIcon(source: string | null | undefined): IconName {
+  if (!source) return FALLBACK_INTEGRATION_ICON;
+  return PROVIDER_CATALOG[source]?.iconName ?? FALLBACK_INTEGRATION_ICON;
+}
+
+export interface IntegrationIconProps extends Omit<ComponentProps<typeof Icon>, 'name'> {
+  source: string | null | undefined;
+}
+
+/**
+ * Preserves the base icon props so callers can decide whether the glyph is
+ * decorative or labeled.
+ */
+export function IntegrationIcon({source, ...props}: IntegrationIconProps) {
+  return <Icon name={getIntegrationIcon(source)} {...props} />;
+}