@shipfox/api-integration-core 2.0.0

package/src/presentation/routes/list-providers.test.ts

@@ -0,0 +1,113 @@
+import {giteaProviderModule} from '#providers/gitea.js';
+import {linearProviderModule} from '#providers/linear.js';
+import {createTestApp, sourceProvider, useIntegrationRouteTest} from '#test/route-utils.js';
+
+describe('GET /integration-providers', () => {
+  useIntegrationRouteTest();
+
+  it('requires user auth', async () => {
+    const app = await createTestApp([sourceProvider()]);
+
+    const res = await app.inject({
+      method: 'GET',
+      url: '/integration-providers',
+    });
+
+    expect(res.statusCode).toBe(401);
+  });
+
+  it('lists providers by capability', async () => {
+    const app = await createTestApp([
+      sourceProvider(),
+      {
+        provider: 'github',
+        displayName: 'GitHub',
+      },
+    ]);
+
+    const res = await app.inject({
+      method: 'GET',
+      url: '/integration-providers?capability=source_control',
+      headers: {authorization: 'Bearer user'},
+    });
+
+    expect(res.statusCode).toBe(200);
+    expect(res.json().providers.map((provider: {provider: string}) => provider.provider)).toEqual([
+      'gitea',
+    ]);
+  });
+
+  it('lists providers with agent tools capability', async () => {
+    const app = await createTestApp([
+      sourceProvider(),
+      {
+        provider: 'github',
+        displayName: 'GitHub',
+        adapters: {
+          agent_tools: {
+            catalog: () => [],
+            selectionCatalog: () => ({selectors: []}),
+            openSession: async () => {
+              await Promise.resolve();
+              return {
+                call: async () => {
+                  await Promise.resolve();
+                  return {};
+                },
+              };
+            },
+          },
+        },
+      },
+    ]);
+
+    const res = await app.inject({
+      method: 'GET',
+      url: '/integration-providers?capability=agent_tools',
+      headers: {authorization: 'Bearer user'},
+    });
+
+    expect(res.statusCode).toBe(200);
+    expect(res.json().providers).toEqual([
+      {
+        provider: 'github',
+        display_name: 'GitHub',
+        capabilities: ['agent_tools'],
+      },
+    ]);
+  });
+
+  it('surfaces the gitea provider once its module is registered', async () => {
+    const {provider} = await giteaProviderModule.load();
+    const app = await createTestApp([provider]);
+
+    const res = await app.inject({
+      method: 'GET',
+      url: '/integration-providers',
+      headers: {authorization: 'Bearer user'},
+    });
+
+    expect(res.statusCode).toBe(200);
+    expect(res.json().providers.map((entry: {provider: string}) => entry.provider)).toContain(
+      'gitea',
+    );
+  });
+
+  it('surfaces the Linear provider with agent tools once its module is registered', async () => {
+    const {provider} = await linearProviderModule.load();
+    const app = await createTestApp([provider]);
+
+    const res = await app.inject({
+      method: 'GET',
+      url: '/integration-providers',
+      headers: {authorization: 'Bearer user'},
+    });
+
+    expect(res.statusCode).toBe(200);
+    expect(res.json().providers).toContainEqual({
+      provider: 'linear',
+      display_name: 'Linear',
+      capabilities: ['agent_tools'],
+    });
+  });
+});

package/src/presentation/routes/list-providers.ts

@@ -0,0 +1,28 @@
+import {AUTH_USER} from '@shipfox/api-auth-context';
+import {
+  listIntegrationProvidersQuerySchema,
+  listIntegrationProvidersResponseSchema,
+} from '@shipfox/api-integration-core-dto';
+import {defineRoute} from '@shipfox/node-fastify';
+import type {IntegrationProviderRegistry} from '#core/providers/registry.js';
+import {toIntegrationProviderDto} from '#presentation/dto/integrations.js';
+
+export function createListIntegrationProvidersRoute(registry: IntegrationProviderRegistry) {
+  return defineRoute({
+    method: 'GET',
+    path: '/integration-providers',
+    auth: AUTH_USER,
+    description: 'List integration providers available to the API.',
+    schema: {
+      querystring: listIntegrationProvidersQuerySchema,
+      response: {
+        200: listIntegrationProvidersResponseSchema,
+      },
+    },
+    handler: async (request) => {
+      await Promise.resolve();
+      const providers = registry.list(request.query.capability);
+      return {providers: providers.map(toIntegrationProviderDto)};
+    },
+  });
+}

package/src/presentation/routes/list-repositories.test.ts

@@ -0,0 +1,150 @@
+import {IntegrationProviderError} from '#core/errors.js';
+import {upsertIntegrationConnection} from '#db/connections.js';
+import {createTestApp, sourceProvider, useIntegrationRouteTest} from '#test/route-utils.js';
+
+describe('GET /integration-connections/:connectionId/repositories', () => {
+  const context = useIntegrationRouteTest();
+
+  it('loads a connection before authorizing repository listing', async () => {
+    const app = await createTestApp([sourceProvider()]);
+    const connection = await upsertIntegrationConnection({
+      workspaceId: context.workspaceId,
+      provider: 'gitea',
+      externalAccountId: 'gitea-owner',
+      slug: 'gitea_owner',
+      displayName: 'Gitea',
+    });
+
+    const res = await app.inject({
+      method: 'GET',
+      url: `/integration-connections/${connection.id}/repositories`,
+      headers: {authorization: 'Bearer user'},
+    });
+
+    expect(res.statusCode).toBe(200);
+    expect(res.json().repositories[0].full_name).toBe('gitea-owner/platform');
+  });
+
+  it('returns 404 when connection is missing', async () => {
+    const app = await createTestApp([sourceProvider()]);
+
+    const res = await app.inject({
+      method: 'GET',
+      url: `/integration-connections/${crypto.randomUUID()}/repositories`,
+      headers: {authorization: 'Bearer user'},
+    });
+
+    expect(res.statusCode).toBe(404);
+    expect(res.json().code).toBe('integration-connection-not-found');
+  });
+
+  it('rejects inactive connections', async () => {
+    const app = await createTestApp([sourceProvider()]);
+    const connection = await upsertIntegrationConnection({
+      workspaceId: context.workspaceId,
+      provider: 'gitea',
+      externalAccountId: 'gitea-owner',
+      slug: 'gitea_owner',
+      displayName: 'Gitea',
+      lifecycleStatus: 'disabled',
+    });
+
+    const res = await app.inject({
+      method: 'GET',
+      url: `/integration-connections/${connection.id}/repositories`,
+      headers: {authorization: 'Bearer user'},
+    });
+
+    expect(res.statusCode).toBe(422);
+    expect(res.json().code).toBe('integration-connection-inactive');
+  });
+
+  it('rejects connections without source-control capability', async () => {
+    const app = await createTestApp([
+      sourceProvider({
+        provider: 'github',
+        displayName: 'GitHub',
+        adapters: {},
+      }),
+    ]);
+    const connection = await upsertIntegrationConnection({
+      workspaceId: context.workspaceId,
+      provider: 'github',
+      externalAccountId: 'team-1',
+      slug: 'github_team_1',
+      displayName: 'GitHub',
+    });
+
+    const res = await app.inject({
+      method: 'GET',
+      url: `/integration-connections/${connection.id}/repositories`,
+      headers: {authorization: 'Bearer user'},
+    });
+
+    expect(res.statusCode).toBe(422);
+    expect(res.json().code).toBe('integration-capability-unavailable');
+  });
+
+  it('returns a stable error when the connection provider is not registered', async () => {
+    const app = await createTestApp([]);
+    const connection = await upsertIntegrationConnection({
+      workspaceId: context.workspaceId,
+      provider: 'github',
+      externalAccountId: 'installation-1',
+      slug: 'github_installation_1',
+      displayName: 'GitHub',
+    });
+
+    const res = await app.inject({
+      method: 'GET',
+      url: `/integration-connections/${connection.id}/repositories`,
+      headers: {authorization: 'Bearer user'},
+    });
+
+    expect(res.statusCode).toBe(422);
+    expect(res.json().code).toBe('integration-provider-unavailable');
+  });
+
+  it('maps provider repository listing errors', async () => {
+    const app = await createTestApp([
+      sourceProvider({
+        adapters: {
+          source_control: {
+            listRepositories: async () => {
+              await Promise.resolve();
+              throw new IntegrationProviderError('rate-limited', 'Provider rate limited', 60);
+            },
+            resolveRepository: async () => {
+              await Promise.resolve();
+              throw new Error('not used');
+            },
+            listFiles: async () => {
+              await Promise.resolve();
+              return {files: [], nextCursor: null};
+            },
+            fetchFile: async () => {
+              await Promise.resolve();
+              throw new Error('not used');
+            },
+          },
+        },
+      }),
+    ]);
+    const connection = await upsertIntegrationConnection({
+      workspaceId: context.workspaceId,
+      provider: 'gitea',
+      externalAccountId: 'gitea-owner',
+      slug: 'gitea_owner',
+      displayName: 'Gitea',
+    });
+
+    const res = await app.inject({
+      method: 'GET',
+      url: `/integration-connections/${connection.id}/repositories`,
+      headers: {authorization: 'Bearer user'},
+    });
+
+    expect(res.statusCode).toBe(429);
+    expect(res.json().code).toBe('rate-limited');
+  });
+});

package/src/presentation/routes/list-repositories.ts

@@ -0,0 +1,47 @@
+import {AUTH_USER, requireWorkspaceAccess} from '@shipfox/api-auth-context';
+import {
+  listRepositoriesParamsSchema,
+  listRepositoriesQuerySchema,
+  listRepositoriesResponseSchema,
+} from '@shipfox/api-integration-core-dto';
+import {defineRoute} from '@shipfox/node-fastify';
+import type {IntegrationSourceControlService} from '#core/source-control-service.js';
+import {toRepositoryDto} from '#presentation/dto/integrations.js';
+import {integrationRouteErrorHandler} from './errors.js';
+
+export function createListRepositoriesRoute(sourceControl: IntegrationSourceControlService) {
+  return defineRoute({
+    method: 'GET',
+    path: '/integration-connections/:connectionId/repositories',
+    auth: AUTH_USER,
+    description: 'List repositories visible to a source-control integration connection.',
+    schema: {
+      params: listRepositoriesParamsSchema,
+      querystring: listRepositoriesQuerySchema,
+      response: {
+        200: listRepositoriesResponseSchema,
+      },
+    },
+    errorHandler: integrationRouteErrorHandler,
+    handler: async (request) => {
+      const {connectionId} = request.params;
+      const connection = await sourceControl.getConnection(connectionId);
+
+      requireWorkspaceAccess({request, workspaceId: connection.workspaceId});
+
+      const page = await sourceControl.listRepositories({
+        connection,
+        limit: request.query.limit,
+        cursor: request.query.cursor,
+        search: request.query.search,
+      });
+
+      return {
+        repositories: page.repositories.map((repository) =>
+          toRepositoryDto(connection.id, repository),
+        ),
+        next_cursor: page.nextCursor,
+      };
+    },
+  });
+}

package/src/presentation/routes/manage-connections.test.ts

@@ -0,0 +1,125 @@
+import {getIntegrationConnectionById, upsertIntegrationConnection} from '#db/connections.js';
+import {createTestApp, sourceProvider, useIntegrationRouteTest} from '#test/route-utils.js';
+
+describe('PATCH /integration-connections/:connectionId', () => {
+  const context = useIntegrationRouteTest();
+
+  it('updates a connection lifecycle status', async () => {
+    const app = await createTestApp([sourceProvider()]);
+    const connection = await upsertIntegrationConnection({
+      workspaceId: context.workspaceId,
+      provider: 'gitea',
+      externalAccountId: 'gitea-owner',
+      slug: 'gitea_owner',
+      displayName: 'Gitea',
+    });
+
+    const res = await app.inject({
+      method: 'PATCH',
+      url: `/integration-connections/${connection.id}`,
+      headers: {authorization: 'Bearer user'},
+      payload: {lifecycle_status: 'disabled'},
+    });
+
+    const reloaded = await getIntegrationConnectionById(connection.id);
+    expect(res.statusCode).toBe(200);
+    expect(res.json().lifecycle_status).toBe('disabled');
+    expect(res.json().capabilities).toEqual(['source_control']);
+    expect(reloaded?.lifecycleStatus).toBe('disabled');
+  });
+
+  it('returns not-found for a missing connection', async () => {
+    const app = await createTestApp([sourceProvider()]);
+
+    const res = await app.inject({
+      method: 'PATCH',
+      url: `/integration-connections/${crypto.randomUUID()}`,
+      headers: {authorization: 'Bearer user'},
+      payload: {lifecycle_status: 'disabled'},
+    });
+
+    expect(res.statusCode).toBe(404);
+    expect(res.json().code).toBe('not-found');
+  });
+
+  it('rejects system-owned lifecycle statuses', async () => {
+    const app = await createTestApp([sourceProvider()]);
+    const connection = await upsertIntegrationConnection({
+      workspaceId: context.workspaceId,
+      provider: 'gitea',
+      externalAccountId: 'gitea-owner',
+      slug: 'gitea_owner',
+      displayName: 'Gitea',
+    });
+
+    const res = await app.inject({
+      method: 'PATCH',
+      url: `/integration-connections/${connection.id}`,
+      headers: {authorization: 'Bearer user'},
+      payload: {lifecycle_status: 'error'},
+    });
+
+    const reloaded = await getIntegrationConnectionById(connection.id);
+    expect(res.statusCode).toBe(400);
+    expect(reloaded?.lifecycleStatus).toBe('active');
+  });
+
+  it('returns membership errors', async () => {
+    const app = await createTestApp([sourceProvider()]);
+    const connection = await upsertIntegrationConnection({
+      workspaceId: crypto.randomUUID(),
+      provider: 'gitea',
+      externalAccountId: 'gitea-owner',
+      slug: 'gitea_owner',
+      displayName: 'Gitea',
+    });
+
+    const res = await app.inject({
+      method: 'PATCH',
+      url: `/integration-connections/${connection.id}`,
+      headers: {authorization: 'Bearer user'},
+      payload: {lifecycle_status: 'disabled'},
+    });
+
+    expect(res.statusCode).toBe(403);
+    expect(res.json().code).toBe('forbidden');
+  });
+});
+
+describe('DELETE /integration-connections/:connectionId', () => {
+  const context = useIntegrationRouteTest();
+
+  it('deletes a connection', async () => {
+    const app = await createTestApp([sourceProvider()]);
+    const connection = await upsertIntegrationConnection({
+      workspaceId: context.workspaceId,
+      provider: 'gitea',
+      externalAccountId: 'gitea-owner',
+      slug: 'gitea_owner',
+      displayName: 'Gitea',
+    });
+
+    const res = await app.inject({
+      method: 'DELETE',
+      url: `/integration-connections/${connection.id}`,
+      headers: {authorization: 'Bearer user'},
+    });
+
+    const reloaded = await getIntegrationConnectionById(connection.id);
+    expect(res.statusCode).toBe(204);
+    expect(reloaded).toBeUndefined();
+  });
+
+  it('returns not-found for a missing connection', async () => {
+    const app = await createTestApp([sourceProvider()]);
+
+    const res = await app.inject({
+      method: 'DELETE',
+      url: `/integration-connections/${crypto.randomUUID()}`,
+      headers: {authorization: 'Bearer user'},
+    });
+
+    expect(res.statusCode).toBe(404);
+    expect(res.json().code).toBe('not-found');
+  });
+});

package/src/presentation/routes/manage-connections.ts

@@ -0,0 +1,77 @@
+import {AUTH_USER, requireWorkspaceAccess} from '@shipfox/api-auth-context';
+import {
+  integrationConnectionDtoSchema,
+  updateIntegrationConnectionBodySchema,
+} from '@shipfox/api-integration-core-dto';
+import {ClientError, defineRoute} from '@shipfox/node-fastify';
+import {z} from 'zod';
+import type {IntegrationProviderRegistry} from '#core/providers/registry.js';
+import {
+  deleteIntegrationConnection,
+  getIntegrationConnectionById,
+  updateIntegrationConnectionLifecycleStatus,
+} from '#db/connections.js';
+import {toIntegrationConnectionDto} from '#presentation/dto/integrations.js';
+
+const connectionParamsSchema = z.object({
+  connectionId: z.string().uuid(),
+});
+
+export function createUpdateIntegrationConnectionRoute(registry: IntegrationProviderRegistry) {
+  return defineRoute({
+    method: 'PATCH',
+    path: '/integration-connections/:connectionId',
+    auth: AUTH_USER,
+    description: 'Update an integration connection.',
+    schema: {
+      params: connectionParamsSchema,
+      body: updateIntegrationConnectionBodySchema,
+      response: {
+        200: integrationConnectionDtoSchema,
+      },
+    },
+    handler: async (request) => {
+      const connection = await getIntegrationConnectionById(request.params.connectionId);
+      if (!connection) {
+        throw new ClientError('Integration connection not found', 'not-found', {status: 404});
+      }
+
+      requireWorkspaceAccess({request, workspaceId: connection.workspaceId});
+      const updated = await updateIntegrationConnectionLifecycleStatus({
+        id: connection.id,
+        lifecycleStatus: request.body.lifecycle_status,
+      });
+      if (!updated) {
+        throw new ClientError('Integration connection not found', 'not-found', {status: 404});
+      }
+
+      const provider = registry.list().find((candidate) => candidate.provider === updated.provider);
+      return toIntegrationConnectionDto(updated, {capabilities: provider?.capabilities ?? []});
+    },
+  });
+}
+
+export function createDeleteIntegrationConnectionRoute() {
+  return defineRoute({
+    method: 'DELETE',
+    path: '/integration-connections/:connectionId',
+    auth: AUTH_USER,
+    description: 'Delete an integration connection.',
+    schema: {
+      params: connectionParamsSchema,
+      response: {
+        204: z.void(),
+      },
+    },
+    handler: async (request, reply) => {
+      const connection = await getIntegrationConnectionById(request.params.connectionId);
+      if (!connection) {
+        throw new ClientError('Integration connection not found', 'not-found', {status: 404});
+      }
+
+      requireWorkspaceAccess({request, workspaceId: connection.workspaceId});
+      await deleteIntegrationConnection({id: connection.id});
+      reply.status(204);
+    },
+  });
+}

package/src/providers/connection-slug.ts

@@ -0,0 +1,19 @@
+import {ConnectionSlugConflictError} from '@shipfox/api-integration-core-dto';
+import {isIntegrationConnectionSlugUniqueViolation} from '#db/connections.js';
+
+const MAX_CONNECTION_SLUG_ATTEMPTS = 3;
+
+export async function retryConnectionSlugCollision<T>(operation: () => Promise<T>): Promise<T> {
+  for (let attempt = 1; ; attempt += 1) {
+    try {
+      return await operation();
+    } catch (error) {
+      if (!isIntegrationConnectionSlugUniqueViolation(error)) {
+        throw error;
+      }
+      if (attempt >= MAX_CONNECTION_SLUG_ATTEMPTS) {
+        throw new ConnectionSlugConflictError(error);
+      }
+    }
+  }
+}

package/src/providers/cron.ts

@@ -0,0 +1,13 @@
+import {config} from '#config.js';
+import type {IntegrationProviderModule} from '#providers/types.js';
+
+export const cronProviderModule: IntegrationProviderModule = {
+  id: 'cron',
+  enabled: config.INTEGRATIONS_ENABLE_CRON_PROVIDER,
+  load: async () => ({
+    provider: {
+      provider: 'cron',
+      displayName: 'Cron',
+    },
+  }),
+};

package/src/providers/gitea.ts

@@ -0,0 +1,103 @@
+import {
+  type IntegrationConnection as CoreIntegrationConnection,
+  slugifyConnectionSlug,
+} from '@shipfox/api-integration-core-dto';
+import type {ConnectGiteaConnectionInput} from '@shipfox/api-integration-gitea';
+import {config} from '#config.js';
+import {
+  getIntegrationConnectionById,
+  resolveUniqueConnectionSlug,
+  upsertIntegrationConnection,
+} from '#db/connections.js';
+import {db} from '#db/db.js';
+import {publishSourcePush, recordDeliveryOnly} from '#db/webhook-deliveries.js';
+import {retryConnectionSlugCollision} from '#providers/connection-slug.js';
+import type {IntegrationModuleParts, IntegrationProviderModule} from '#providers/types.js';
+
+// Stable migration-tracking table name for the Gitea provider database. This
+// must NOT depend on the provider's position in the module `database` array. A
+// positional name would shift if a provider is flag-disabled and silently
+// re-run migrations against existing tables.
+const GITEA_MIGRATIONS_TABLE = '__drizzle_migrations_integrations_gitea';
+
+async function loadGiteaModuleParts(): Promise<IntegrationModuleParts> {
+  const {
+    createGiteaIntegrationProvider,
+    getGiteaConnectionByOrg,
+    upsertGiteaConnection,
+    db: giteaDb,
+    migrationsPath: giteaMigrationsPath,
+  } = await import('@shipfox/api-integration-gitea');
+
+  async function getExistingGiteaConnection(input: {
+    org: string;
+  }): Promise<CoreIntegrationConnection<'gitea'> | undefined> {
+    const row = await getGiteaConnectionByOrg(input.org);
+    if (!row) return undefined;
+    const connection = await getIntegrationConnectionById(row.connectionId);
+    if (!connection) return undefined;
+    return connection as CoreIntegrationConnection<'gitea'>;
+  }
+
+  async function connectGiteaConnection(
+    input: ConnectGiteaConnectionInput,
+  ): Promise<CoreIntegrationConnection<'gitea'>> {
+    return await retryConnectionSlugCollision(() =>
+      db().transaction(async (tx) => {
+        const baseSlug = slugifyConnectionSlug(`gitea_${input.org}`, {fallback: 'gitea'});
+        const slug = await resolveUniqueConnectionSlug(
+          {
+            workspaceId: input.workspaceId,
+            provider: 'gitea',
+            externalAccountId: input.org,
+            baseSlug,
+          },
+          {tx},
+        );
+        const connection = await upsertIntegrationConnection(
+          {
+            workspaceId: input.workspaceId,
+            provider: 'gitea',
+            externalAccountId: input.org,
+            slug,
+            displayName: input.displayName,
+            lifecycleStatus: 'active',
+          },
+          {tx},
+        );
+
+        await upsertGiteaConnection(
+          {
+            connectionId: connection.id,
+            org: input.org,
+          },
+          {tx},
+        );
+
+        return connection as CoreIntegrationConnection<'gitea'>;
+      }),
+    );
+  }
+
+  return {
+    provider: createGiteaIntegrationProvider({
+      getExistingGiteaConnection,
+      connectGiteaConnection,
+      publishSourcePush,
+      recordDeliveryOnly,
+      getIntegrationConnectionById,
+      coreDb: db,
+    }),
+    database: {
+      db: giteaDb,
+      migrationsPath: giteaMigrationsPath,
+      migrationsTableName: GITEA_MIGRATIONS_TABLE,
+    },
+  };
+}
+
+export const giteaProviderModule: IntegrationProviderModule = {
+  id: 'gitea',
+  enabled: config.INTEGRATIONS_ENABLE_GITEA_PROVIDER,
+  load: loadGiteaModuleParts,
+};