@shipfox/client-integrations 4.0.0 → 6.0.1

package/src/hooks/api/integrations.test.ts

@@ -10,8 +10,8 @@ import {
 
 function connection(overrides: Partial<IntegrationConnectionDto> = {}): IntegrationConnectionDto {
   return {
-    id: 'c1',
-    workspace_id: 'ws-1',
+    id: '11111111-1111-4111-8111-111111111111',
+    workspace_id: '22222222-2222-4222-8222-222222222222',
     provider: 'github',
     external_account_id: 'acct',
     slug: 'github_acct',
@@ -40,19 +40,23 @@ describe('listSourceConnections', () => {
       return Promise.resolve(
         jsonResponse({
           connections: [
-            connection({id: 'active-1', lifecycle_status: 'active'}),
-            connection({id: 'disabled-1', lifecycle_status: 'disabled'}),
-            connection({id: 'error-1', lifecycle_status: 'error'}),
+            connection({id: '33333333-3333-4333-8333-333333333333', lifecycle_status: 'active'}),
+            connection({id: '44444444-4444-4444-8444-444444444444', lifecycle_status: 'disabled'}),
+            connection({id: '55555555-5555-4555-8555-555555555555', lifecycle_status: 'error'}),
           ],
         }),
       );
     });
     configureApiClient({baseUrl: 'https://api.example.test', fetchImpl});
 
-    const result = await listSourceConnections({workspaceId: 'ws-1'});
+    const result = await listSourceConnections({
+      workspaceId: '22222222-2222-4222-8222-222222222222',
+    });
 
     expect(requestedUrl).toContain('capability=source_control');
-    expect(result.connections.map((connection) => connection.id)).toEqual(['active-1']);
+    expect(result.map((connection) => connection.id)).toEqual([
+      '33333333-3333-4333-8333-333333333333',
+    ]);
   });
 });
 
@@ -63,11 +67,20 @@ describe('Slack transport', () => {
       baseUrl: 'https://api.example.test',
       fetchImpl: vi.fn((input, init) => {
         requests.push(new Request(input, init));
-        return Promise.resolve(jsonResponse(connection({provider: 'slack'})));
+        const url = input instanceof Request ? input.url : String(input);
+        return Promise.resolve(
+          jsonResponse(
+            url.endsWith('/install')
+              ? {install_url: 'https://slack.example.test/install'}
+              : connection({provider: 'slack'}),
+          ),
+        );
       }),
     });
 
-    await createSlackInstall({workspace_id: '11111111-1111-4111-8111-111111111111'});
+    const install = await createSlackInstall({
+      workspace_id: '11111111-1111-4111-8111-111111111111',
+    });
     await completeSlackCallback({
       query: {code: 'grant code', state: 'signed state'},
       token: 'session-token',
@@ -77,6 +90,7 @@ describe('Slack transport', () => {
     expect(await requests[0]?.json()).toEqual({
       workspace_id: '11111111-1111-4111-8111-111111111111',
     });
+    expect(install).toEqual({installUrl: 'https://slack.example.test/install'});
     expect(requests[1]?.url).toBe(
       'https://api.example.test/integrations/slack/callback/api?code=grant+code&state=signed+state',
     );
@@ -89,24 +103,31 @@ describe('Linear transport', () => {
     const requests: Request[] = [];
     const fetchImpl = vi.fn((input: RequestInfo | URL, init?: RequestInit) => {
       requests.push(new Request(input, init));
+      const url = input instanceof Request ? input.url : String(input);
       return Promise.resolve(
-        jsonResponse({
-          id: 'connection-1',
-          workspace_id: '11111111-1111-4111-8111-111111111111',
-          provider: 'linear',
-          external_account_id: 'linear-org',
-          slug: 'linear_org',
-          display_name: 'Linear org',
-          lifecycle_status: 'active',
-          capabilities: [],
-          created_at: '2026-01-01T00:00:00.000Z',
-          updated_at: '2026-01-01T00:00:00.000Z',
-        }),
+        jsonResponse(
+          url.endsWith('/install')
+            ? {install_url: 'https://linear.example.test/install'}
+            : {
+                id: '33333333-3333-4333-8333-333333333333',
+                workspace_id: '11111111-1111-4111-8111-111111111111',
+                provider: 'linear',
+                external_account_id: 'linear-org',
+                slug: 'linear_org',
+                display_name: 'Linear org',
+                lifecycle_status: 'active',
+                capabilities: [],
+                created_at: '2026-01-01T00:00:00.000Z',
+                updated_at: '2026-01-01T00:00:00.000Z',
+              },
+        ),
       );
     });
     configureApiClient({baseUrl: 'https://api.example.test', fetchImpl});
 
-    await createLinearInstall({workspace_id: '11111111-1111-4111-8111-111111111111'});
+    const install = await createLinearInstall({
+      workspace_id: '11111111-1111-4111-8111-111111111111',
+    });
     await completeLinearCallback({
       query: {code: 'grant code', state: 'signed state'},
       token: 'session-token',
@@ -124,6 +145,7 @@ describe('Linear transport', () => {
     expect(await requests[0]?.json()).toEqual({
       workspace_id: '11111111-1111-4111-8111-111111111111',
     });
+    expect(install).toEqual({installUrl: 'https://linear.example.test/install'});
     expect(requests[1]?.url).toBe(
       'https://api.example.test/integrations/linear/callback/api?code=grant+code&state=signed+state',
     );

package/src/hooks/api/integrations.ts

@@ -1,41 +1,71 @@
 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,
+import {
+  integrationConnectionDtoSchema,
+  listIntegrationConnectionsResponseSchema,
+  listIntegrationProvidersResponseSchema,
+  listRepositoriesResponseSchema,
+} from '@shipfox/api-integration-core-dto';
+import type {CreateGiteaConnectionBodyDto} from '@shipfox/api-integration-gitea-dto';
+import {createGiteaConnectionResponseSchema} from '@shipfox/api-integration-gitea-dto';
+import type {CreateGithubInstallBodyDto} from '@shipfox/api-integration-github-dto';
+import {
+  createGithubInstallResponseSchema,
+  githubCallbackResponseSchema,
 } from '@shipfox/api-integration-github-dto';
 import type {
   CreateLinearInstallBodyDto,
-  CreateLinearInstallResponseDto,
   LinearCallbackQueryDto,
-  LinearCallbackResponseDto,
+} from '@shipfox/api-integration-linear-dto';
+import {
+  createLinearInstallResponseSchema,
+  linearCallbackResponseSchema,
 } from '@shipfox/api-integration-linear-dto';
 import type {
   CreateSentryInstallBodyDto,
-  CreateSentryInstallResponseDto,
   SentryConnectBodyDto,
-  SentryConnectResponseDto,
+} from '@shipfox/api-integration-sentry-dto';
+import {
+  createSentryInstallResponseSchema,
+  sentryConnectResponseSchema,
 } from '@shipfox/api-integration-sentry-dto';
 import type {
   CreateSlackInstallBodyDto,
-  CreateSlackInstallResponseDto,
   SlackCallbackQueryDto,
-  SlackCallbackResponseDto,
 } from '@shipfox/api-integration-slack-dto';
-import {apiRequest} from '@shipfox/client-api';
-import {useInfiniteQuery, useMutation, useQuery, useQueryClient} from '@tanstack/react-query';
+import {
+  createSlackInstallResponseSchema,
+  slackCallbackResponseSchema,
+} from '@shipfox/api-integration-slack-dto';
+import {checkedApiRequest, emptyResponseSchema} from '@shipfox/client-api';
+import {
+  type FetchQueryOptions,
+  type InfiniteData,
+  infiniteQueryOptions,
+  queryOptions,
+  type UseInfiniteQueryOptions,
+  useInfiniteQuery,
+  useMutation,
+  useQuery,
+  useQueryClient,
+} from '@tanstack/react-query';
+import {
+  type InstallRedirect,
+  type IntegrationConnection,
+  type IntegrationProvider,
+  isUsableConnection,
+  type RepositoryPage,
+} from '#core/models.js';
 import {serializeLinearCallbackQuery} from '#linear-callback.js';
 import {serializeSlackCallbackQuery} from '#slack-callback.js';
+import {
+  toInstallRedirect,
+  toIntegrationConnection,
+  toIntegrationProvider,
+  toRepository,
+} from './integration-mapper.js';
 
 export const integrationsQueryKeys = {
   all: ['integrations'] as const,
@@ -54,18 +84,62 @@ export const integrationsQueryKeys = {
     [...integrationsQueryKeys.all, 'repositories', connectionId, search] as const,
 };
 
+type SourceConnectionsQueryKey =
+  | ReturnType<typeof integrationsQueryKeys.sourceConnections>
+  | readonly ['integrations', 'source-connections'];
+
+type SourceConnectionsQueryOptions = FetchQueryOptions<
+  IntegrationConnection[],
+  Error,
+  IntegrationConnection[],
+  SourceConnectionsQueryKey
+>;
+
+type ProvidersQueryKey = ReturnType<typeof integrationsQueryKeys.providers>;
+
+type ProvidersQueryOptions = FetchQueryOptions<
+  IntegrationProvider[],
+  Error,
+  IntegrationProvider[],
+  ProvidersQueryKey
+>;
+
+type ConnectionsQueryKey =
+  | ReturnType<typeof integrationsQueryKeys.connections>
+  | readonly ['integrations', 'connections'];
+
+type ConnectionsQueryOptions = FetchQueryOptions<
+  IntegrationConnection[],
+  Error,
+  IntegrationConnection[],
+  ConnectionsQueryKey
+>;
+
+type RepositoriesQueryKey =
+  | ReturnType<typeof integrationsQueryKeys.repositories>
+  | readonly ['integrations', 'repositories'];
+
+type RepositoriesInfiniteQueryOptions = UseInfiniteQueryOptions<
+  RepositoryPage,
+  Error,
+  InfiniteData<RepositoryPage, string | undefined>,
+  RepositoriesQueryKey,
+  string | undefined
+>;
+
 export async function listIntegrationProviders({
   capability,
   signal,
 }: {
   capability?: IntegrationCapabilityDto;
   signal?: AbortSignal;
-}) {
+}): Promise<IntegrationProvider[]> {
   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});
+  const response = await checkedApiRequest(listIntegrationProvidersResponseSchema, path, {signal});
+  return response.providers.map(toIntegrationProvider);
 }
 
 export async function listIntegrationConnections({
@@ -76,13 +150,15 @@ export async function listIntegrationConnections({
   workspaceId: string;
   capability?: IntegrationCapabilityDto | undefined;
   signal?: AbortSignal | undefined;
-}) {
+}): Promise<IntegrationConnection[]> {
   const search = new URLSearchParams({workspace_id: workspaceId});
   if (capability) search.set('capability', capability);
-  return await apiRequest<ListIntegrationConnectionsResponseDto>(
+  const response = await checkedApiRequest(
+    listIntegrationConnectionsResponseSchema,
     `/integration-connections?${search.toString()}`,
     {signal},
   );
+  return response.connections.map(toIntegrationConnection);
 }
 
 export async function listSourceConnections({
@@ -91,8 +167,8 @@ export async function listSourceConnections({
 }: {
   workspaceId: string;
   signal?: AbortSignal;
-}) {
-  const result = await listIntegrationConnections({
+}): Promise<IntegrationConnection[]> {
+  const connections = await listIntegrationConnections({
     workspaceId,
     capability: 'source_control',
     signal,
@@ -100,47 +176,100 @@ export async function listSourceConnections({
   // 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',
-    ),
-  };
+  return connections.filter(isUsableConnection);
 }
 
-export async function createGiteaConnection(body: CreateGiteaConnectionBodyDto) {
-  return await apiRequest<CreateGiteaConnectionResponseDto>('/integrations/gitea/connections', {
-    method: 'POST',
-    body,
+export function sourceConnectionsQueryOptions(
+  workspaceId: string | undefined,
+): SourceConnectionsQueryOptions {
+  return queryOptions({
+    queryKey: workspaceId
+      ? integrationsQueryKeys.sourceConnections(workspaceId)
+      : ([...integrationsQueryKeys.all, 'source-connections'] as const),
+    enabled: Boolean(workspaceId),
+    queryFn: ({signal}) => listSourceConnections({workspaceId: workspaceId ?? '', signal}),
   });
 }
 
-export async function createGithubInstall(body: CreateGithubInstallBodyDto) {
-  return await apiRequest<CreateGithubInstallResponseDto>('/integrations/github/install', {
-    method: 'POST',
-    body,
-  });
+export async function createGiteaConnection(
+  body: CreateGiteaConnectionBodyDto,
+): Promise<IntegrationConnection> {
+  const response = await checkedApiRequest(
+    createGiteaConnectionResponseSchema,
+    '/integrations/gitea/connections',
+    {
+      method: 'POST',
+      body,
+    },
+  );
+  return toIntegrationConnection(response);
 }
 
-export async function createSentryInstall(body: CreateSentryInstallBodyDto) {
-  return await apiRequest<CreateSentryInstallResponseDto>('/integrations/sentry/install', {
-    method: 'POST',
-    body,
-  });
+export async function createGithubInstall(
+  body: CreateGithubInstallBodyDto,
+): Promise<InstallRedirect> {
+  return toInstallRedirect(
+    await checkedApiRequest(createGithubInstallResponseSchema, '/integrations/github/install', {
+      method: 'POST',
+      body,
+    }),
+  );
 }
 
-export async function createLinearInstall(body: CreateLinearInstallBodyDto) {
-  return await apiRequest<CreateLinearInstallResponseDto>('/integrations/linear/install', {
-    method: 'POST',
-    body,
-  });
+export async function completeGithubCallback({
+  code,
+  installationId,
+  state,
+  setupAction,
+  token,
+}: {
+  code: string;
+  installationId: number;
+  state: string;
+  setupAction?: string;
+  token: string;
+}): Promise<IntegrationConnection> {
+  const query = new URLSearchParams({code, installation_id: String(installationId), state});
+  if (setupAction) query.set('setup_action', setupAction);
+  const response = await checkedApiRequest(
+    githubCallbackResponseSchema,
+    `/integrations/github/callback/api?${query.toString()}`,
+    {headers: {authorization: `Bearer ${token}`}},
+  );
+  return toIntegrationConnection(response);
 }
 
-export async function createSlackInstall(body: CreateSlackInstallBodyDto) {
-  return await apiRequest<CreateSlackInstallResponseDto>('/integrations/slack/install', {
-    method: 'POST',
-    body,
-  });
+export async function createSentryInstall(
+  body: CreateSentryInstallBodyDto,
+): Promise<InstallRedirect> {
+  return toInstallRedirect(
+    await checkedApiRequest(createSentryInstallResponseSchema, '/integrations/sentry/install', {
+      method: 'POST',
+      body,
+    }),
+  );
+}
+
+export async function createLinearInstall(
+  body: CreateLinearInstallBodyDto,
+): Promise<InstallRedirect> {
+  return toInstallRedirect(
+    await checkedApiRequest(createLinearInstallResponseSchema, '/integrations/linear/install', {
+      method: 'POST',
+      body,
+    }),
+  );
+}
+
+export async function createSlackInstall(
+  body: CreateSlackInstallBodyDto,
+): Promise<InstallRedirect> {
+  return toInstallRedirect(
+    await checkedApiRequest(createSlackInstallResponseSchema, '/integrations/slack/install', {
+      method: 'POST',
+      body,
+    }),
+  );
 }
 
 export async function completeLinearCallback({
@@ -149,11 +278,13 @@ export async function completeLinearCallback({
 }: {
   query: LinearCallbackQueryDto;
   token: string;
-}) {
-  return await apiRequest<LinearCallbackResponseDto>(
+}): Promise<IntegrationConnection> {
+  const response = await checkedApiRequest(
+    linearCallbackResponseSchema,
     `/integrations/linear/callback/api?${serializeLinearCallbackQuery(query)}`,
     {headers: {authorization: `Bearer ${token}`}},
   );
+  return toIntegrationConnection(response);
 }
 
 export async function completeSlackCallback({
@@ -162,21 +293,28 @@ export async function completeSlackCallback({
 }: {
   query: SlackCallbackQueryDto;
   token: string;
-}) {
-  return await apiRequest<SlackCallbackResponseDto>(
+}): Promise<IntegrationConnection> {
+  const response = await checkedApiRequest(
+    slackCallbackResponseSchema,
     `/integrations/slack/callback/api?${serializeSlackCallbackQuery(query)}`,
     {headers: {authorization: `Bearer ${token}`}},
   );
+  return toIntegrationConnection(response);
 }
 
 // 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}`},
-  });
+  const response = await checkedApiRequest(
+    sentryConnectResponseSchema,
+    '/integrations/sentry/connect',
+    {
+      method: 'POST',
+      body,
+      headers: {authorization: `Bearer ${token}`},
+    },
+  );
+  return toIntegrationConnection(response);
 }
 
 export async function listRepositories({
@@ -189,7 +327,7 @@ export async function listRepositories({
   cursor?: string;
   search?: string;
   signal?: AbortSignal;
-}) {
+}): Promise<RepositoryPage> {
   const params = new URLSearchParams();
   if (cursor) params.set('cursor', cursor);
   if (search) params.set('search', search);
@@ -197,7 +335,11 @@ export async function listRepositories({
   const path = query
     ? `/integration-connections/${connectionId}/repositories?${query}`
     : `/integration-connections/${connectionId}/repositories`;
-  return await apiRequest<ListRepositoriesResponseDto>(path, {signal});
+  const response = await checkedApiRequest(listRepositoriesResponseSchema, path, {signal});
+  return {
+    repositories: response.repositories.map(toRepository),
+    ...(response.next_cursor == null ? {} : {nextCursor: response.next_cursor}),
+  };
 }
 
 export async function updateIntegrationConnection({
@@ -206,56 +348,67 @@ export async function updateIntegrationConnection({
 }: {
   connectionId: string;
   body: UpdateIntegrationConnectionBodyDto;
-}) {
-  return await apiRequest<IntegrationConnectionDto>(
+}): Promise<IntegrationConnection> {
+  const response = await checkedApiRequest(
+    integrationConnectionDtoSchema,
     `/integration-connections/${encodeURIComponent(connectionId)}`,
     {method: 'PATCH', body},
   );
+  return toIntegrationConnection(response);
 }
 
 export async function deleteIntegrationConnection({connectionId}: {connectionId: string}) {
-  await apiRequest<void>(`/integration-connections/${encodeURIComponent(connectionId)}`, {
-    method: 'DELETE',
-  });
+  await checkedApiRequest(
+    emptyResponseSchema,
+    `/integration-connections/${encodeURIComponent(connectionId)}`,
+    {
+      method: 'DELETE',
+    },
+  );
 }
 
 export function useIntegrationProvidersQuery(params?: {capability?: IntegrationCapabilityDto}) {
-  const capability = params?.capability;
-  return useQuery({
+  return useQuery(integrationProvidersQueryOptions(params?.capability));
+}
+
+export function integrationProvidersQueryOptions(
+  capability?: IntegrationCapabilityDto,
+): ProvidersQueryOptions {
+  return queryOptions({
     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}),
-  });
+  return useQuery(sourceConnectionsQueryOptions(workspaceId));
 }
 
 export function useIntegrationConnectionsQuery(workspaceId: string | undefined) {
-  return useQuery({
+  return useQuery(integrationConnectionsQueryOptions(workspaceId));
+}
+
+export function integrationConnectionsQueryOptions(
+  workspaceId: string | undefined,
+): ConnectionsQueryOptions {
+  return queryOptions({
     queryKey: workspaceId
       ? integrationsQueryKeys.connections(workspaceId, 'all')
-      : [...integrationsQueryKeys.all, 'connections'],
+      : ([...integrationsQueryKeys.all, 'connections'] as const),
     enabled: Boolean(workspaceId),
     queryFn: ({signal}) => listIntegrationConnections({workspaceId: workspaceId ?? '', signal}),
   });
 }
 
-export function useRepositoriesInfiniteQuery(
+export function repositoriesInfiniteQueryOptions(
   connectionId: string | undefined,
   options?: {search?: string},
-) {
+): RepositoriesInfiniteQueryOptions {
   const trimmedSearch = options?.search?.trim() ?? '';
-  return useInfiniteQuery({
+  return infiniteQueryOptions({
     queryKey: connectionId
       ? integrationsQueryKeys.repositories(connectionId, trimmedSearch)
-      : [...integrationsQueryKeys.all, 'repositories'],
+      : ([...integrationsQueryKeys.all, 'repositories'] as const),
     enabled: Boolean(connectionId),
     initialPageParam: undefined as string | undefined,
     queryFn: ({pageParam, signal}) => {
@@ -267,12 +420,28 @@ export function useRepositoriesInfiniteQuery(
       if (trimmedSearch) args.search = trimmedSearch;
       return listRepositories(args);
     },
-    getNextPageParam: (lastPage) => lastPage.next_cursor ?? undefined,
+    getNextPageParam: (lastPage) => lastPage.nextCursor,
   });
 }
 
+export function useRepositoriesInfiniteQuery(
+  connectionId: string | undefined,
+  options?: {search?: string},
+) {
+  return useInfiniteQuery(repositoriesInfiniteQueryOptions(connectionId, options));
+}
+
 export function useCreateGiteaConnectionMutation() {
-  return useMutation({mutationFn: createGiteaConnection});
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: createGiteaConnection,
+    onSuccess: async (connection) => {
+      await queryClient.invalidateQueries({
+        queryKey: integrationsQueryKeys.connectionsByWorkspace(connection.workspaceId),
+        refetchType: 'all',
+      });
+    },
+  });
 }
 
 export function useCreateLinearInstallMutation() {
@@ -297,7 +466,7 @@ export function useUpdateIntegrationConnectionMutation() {
     mutationFn: updateIntegrationConnection,
     onSuccess: async (connection) => {
       await queryClient.invalidateQueries({
-        queryKey: integrationsQueryKeys.connectionsByWorkspace(connection.workspace_id),
+        queryKey: integrationsQueryKeys.connectionsByWorkspace(connection.workspaceId),
       });
     },
   });