@shipfox/api-integration-core 2.0.0

package/src/core/source-control-service.test.ts

@@ -0,0 +1,230 @@
+import {IntegrationCheckoutUnsupportedError, IntegrationProviderError} from './errors.js';
+import {createIntegrationProviderRegistry} from './providers/registry.js';
+import type {RepositorySnapshot, SourceControlProvider} from './providers/source-control.js';
+import {createSourceControlIntegrationService} from './source-control-service.js';
+
+const repository: RepositorySnapshot = {
+  externalRepositoryId: 'gitea:gitea-owner/platform',
+  owner: 'gitea-owner',
+  name: 'platform',
+  fullName: 'gitea-owner/platform',
+  defaultBranch: 'main',
+  visibility: 'private',
+  cloneUrl: 'https://gitea.local/gitea-owner/platform.git',
+  htmlUrl: 'https://gitea.local/gitea-owner/platform',
+};
+
+describe('integration source-control service', () => {
+  const workspaceId = crypto.randomUUID();
+  const connection = {
+    id: crypto.randomUUID(),
+    workspaceId,
+    provider: 'gitea' as const,
+    externalAccountId: 'gitea-owner',
+    slug: 'gitea_owner',
+    displayName: 'Gitea',
+    lifecycleStatus: 'active' as const,
+    createdAt: new Date(),
+    updatedAt: new Date(),
+  };
+
+  function createService(
+    overrides: Partial<SourceControlProvider> = {},
+    options: {omitCheckoutSpec?: boolean} = {},
+  ) {
+    const sourceControl: SourceControlProvider = {
+      listRepositories: async () => {
+        await Promise.resolve();
+        return {repositories: [repository], nextCursor: null};
+      },
+      resolveRepository: async () => {
+        await Promise.resolve();
+        return repository;
+      },
+      listFiles: async () => {
+        await Promise.resolve();
+        return {
+          files: [{path: '.shipfox/workflows/ci.yml', type: 'file', size: 64}],
+          nextCursor: null,
+        };
+      },
+      fetchFile: async () => {
+        await Promise.resolve();
+        return {path: '.shipfox/workflows/ci.yml', ref: 'main', content: 'name: CI'};
+      },
+      createCheckoutSpec: async (input) => {
+        await Promise.resolve();
+        return {repositoryUrl: repository.cloneUrl, ref: input.ref ?? repository.defaultBranch};
+      },
+      ...overrides,
+    };
+    if (options.omitCheckoutSpec) {
+      delete sourceControl.createCheckoutSpec;
+    }
+    return createSourceControlIntegrationService({
+      registry: createIntegrationProviderRegistry([
+        {
+          provider: 'gitea',
+          displayName: 'Gitea',
+          adapters: {
+            source_control: sourceControl,
+          },
+        },
+      ]),
+      getIntegrationConnectionById: async (connectionId) => {
+        await Promise.resolve();
+        return connectionId === connection.id ? connection : undefined;
+      },
+    });
+  }
+
+  it('resolves a repository through an active source-control connection', async () => {
+    const service = createService();
+
+    const result = await service.resolveRepository({
+      workspaceId,
+      connectionId: connection.id,
+      externalRepositoryId: 'gitea:gitea-owner/platform',
+    });
+
+    expect(result.connection.id).toBe(connection.id);
+    expect(result.repository.externalRepositoryId).toBe('gitea:gitea-owner/platform');
+  });
+
+  it('rejects a missing connection', async () => {
+    const service = createService();
+
+    const result = service.resolveRepository({
+      workspaceId,
+      connectionId: crypto.randomUUID(),
+      externalRepositoryId: 'gitea:gitea-owner/platform',
+    });
+
+    await expect(result).rejects.toThrow('Integration connection not found');
+  });
+
+  it('rejects a connection in another workspace', async () => {
+    const service = createService();
+
+    const result = service.resolveRepository({
+      workspaceId: crypto.randomUUID(),
+      connectionId: connection.id,
+      externalRepositoryId: 'gitea:gitea-owner/platform',
+    });
+
+    await expect(result).rejects.toThrow('requested workspace');
+  });
+
+  it('surfaces provider repository failures', async () => {
+    const service = createService({
+      resolveRepository: async () => {
+        await Promise.resolve();
+        throw new IntegrationProviderError('repository-not-found', 'Repository not found');
+      },
+    });
+
+    const result = service.resolveRepository({
+      workspaceId,
+      connectionId: connection.id,
+      externalRepositoryId: 'gitea:gitea-owner/missing',
+    });
+
+    await expect(result).rejects.toMatchObject({reason: 'repository-not-found'});
+  });
+
+  it('lists files through an active source-control connection', async () => {
+    const service = createService();
+
+    const result = await service.listFiles({
+      workspaceId,
+      connectionId: connection.id,
+      externalRepositoryId: 'gitea:gitea-owner/platform',
+      ref: 'main',
+      prefix: '.shipfox/workflows/',
+      limit: 100,
+    });
+
+    expect(result.files[0]?.path).toBe('.shipfox/workflows/ci.yml');
+  });
+
+  it('fetches files through an active source-control connection', async () => {
+    const service = createService();
+
+    const result = await service.fetchFile({
+      workspaceId,
+      connectionId: connection.id,
+      externalRepositoryId: 'gitea:gitea-owner/platform',
+      ref: 'main',
+      path: '.shipfox/workflows/ci.yml',
+    });
+
+    expect(result.content).toBe('name: CI');
+  });
+
+  it('creates a checkout spec through an active source-control connection', async () => {
+    const createCheckoutSpec = vi.fn(
+      async (input: Parameters<NonNullable<SourceControlProvider['createCheckoutSpec']>>[0]) => {
+        await Promise.resolve();
+        return {repositoryUrl: repository.cloneUrl, ref: input.ref ?? repository.defaultBranch};
+      },
+    );
+    const service = createService({createCheckoutSpec});
+
+    const result = await service.createCheckoutSpec({
+      workspaceId,
+      connectionId: connection.id,
+      externalRepositoryId: 'gitea:gitea-owner/platform',
+      ref: 'feature/x',
+      permissions: {contents: 'write'},
+    });
+
+    expect(result).toEqual({
+      repositoryUrl: 'https://gitea.local/gitea-owner/platform.git',
+      ref: 'feature/x',
+    });
+    expect(createCheckoutSpec).toHaveBeenCalledWith(
+      expect.objectContaining({permissions: {contents: 'write'}}),
+    );
+  });
+
+  it('rejects a checkout spec for a connection in another workspace', async () => {
+    const service = createService();
+
+    const result = service.createCheckoutSpec({
+      workspaceId: crypto.randomUUID(),
+      connectionId: connection.id,
+      externalRepositoryId: 'gitea:gitea-owner/platform',
+    });
+
+    await expect(result).rejects.toThrow('requested workspace');
+  });
+
+  it('surfaces provider checkout failures', async () => {
+    const service = createService({
+      createCheckoutSpec: async () => {
+        await Promise.resolve();
+        throw new IntegrationProviderError('access-denied', 'Checkout not permitted');
+      },
+    });
+
+    const result = service.createCheckoutSpec({
+      workspaceId,
+      connectionId: connection.id,
+      externalRepositoryId: 'gitea:gitea-owner/platform',
+    });
+
+    await expect(result).rejects.toMatchObject({reason: 'access-denied'});
+  });
+
+  it('rejects when the provider does not support creating a checkout spec', async () => {
+    const service = createService({}, {omitCheckoutSpec: true});
+
+    const result = service.createCheckoutSpec({
+      workspaceId,
+      connectionId: connection.id,
+      externalRepositoryId: 'gitea:gitea-owner/platform',
+    });
+
+    await expect(result).rejects.toBeInstanceOf(IntegrationCheckoutUnsupportedError);
+  });
+});

package/src/core/source-control-service.ts

@@ -0,0 +1,161 @@
+import type {IntegrationConnection} from './entities/connection.js';
+import {
+  IntegrationCheckoutUnsupportedError,
+  IntegrationConnectionInactiveError,
+  IntegrationConnectionNotFoundError,
+  IntegrationConnectionWorkspaceMismatchError,
+} from './errors.js';
+import type {IntegrationProviderRegistry} from './providers/registry.js';
+import type {
+  CheckoutPermissions,
+  CheckoutSpec,
+  FilePage,
+  FileSnapshot,
+  RepositoryPage,
+  RepositorySnapshot,
+} from './providers/source-control.js';
+
+export interface IntegrationSourceControlService {
+  getConnection(connectionId: string): Promise<IntegrationConnection>;
+  listRepositories(input: ListSourceRepositoriesInput): Promise<RepositoryPage>;
+  resolveRepository(input: ResolveSourceRepositoryInput): Promise<ResolvedSourceRepository>;
+  listFiles(input: ListSourceFilesInput): Promise<FilePage>;
+  fetchFile(input: FetchSourceFileInput): Promise<FileSnapshot>;
+  createCheckoutSpec(input: CreateSourceCheckoutSpecInput): Promise<CheckoutSpec>;
+}
+
+export interface ListSourceRepositoriesInput {
+  connection: IntegrationConnection;
+  limit: number;
+  cursor?: string | undefined;
+  search?: string | undefined;
+}
+
+export interface ResolveSourceRepositoryInput {
+  workspaceId: string;
+  connectionId: string;
+  externalRepositoryId: string;
+}
+
+export interface ListSourceFilesInput extends ResolveSourceRepositoryInput {
+  ref: string;
+  prefix: string;
+  limit: number;
+  cursor?: string | undefined;
+}
+
+export interface FetchSourceFileInput extends ResolveSourceRepositoryInput {
+  ref: string;
+  path: string;
+}
+
+export interface CreateSourceCheckoutSpecInput extends ResolveSourceRepositoryInput {
+  ref?: string | undefined;
+  permissions?: CheckoutPermissions | undefined;
+}
+
+export interface ResolvedSourceRepository {
+  connection: IntegrationConnection;
+  repository: RepositorySnapshot;
+}
+
+export interface CreateIntegrationSourceControlServiceOptions {
+  registry: IntegrationProviderRegistry;
+  getIntegrationConnectionById: (
+    connectionId: string,
+  ) => Promise<IntegrationConnection | undefined>;
+}
+
+export function createSourceControlIntegrationService({
+  registry,
+  getIntegrationConnectionById,
+}: CreateIntegrationSourceControlServiceOptions): IntegrationSourceControlService {
+  async function getConnection(connectionId: string): Promise<IntegrationConnection> {
+    const connection = await getIntegrationConnectionById(connectionId);
+    if (!connection) throw new IntegrationConnectionNotFoundError(connectionId);
+    if (connection.lifecycleStatus !== 'active') {
+      throw new IntegrationConnectionInactiveError(connection.id);
+    }
+
+    return connection;
+  }
+
+  return {
+    getConnection,
+
+    async listRepositories({connection, limit, cursor, search}) {
+      const sourceControl = registry.getAdapter(connection.provider, 'source_control');
+      return await sourceControl.listRepositories({
+        connection,
+        limit,
+        cursor,
+        search,
+      });
+    },
+
+    async resolveRepository({workspaceId, connectionId, externalRepositoryId}) {
+      const connection = await getConnection(connectionId);
+      if (connection.workspaceId !== workspaceId) {
+        throw new IntegrationConnectionWorkspaceMismatchError(connectionId);
+      }
+      const sourceControl = registry.getAdapter(connection.provider, 'source_control');
+
+      const repository = await sourceControl.resolveRepository({
+        connection,
+        externalRepositoryId,
+      });
+
+      return {connection, repository};
+    },
+
+    async listFiles({workspaceId, connectionId, externalRepositoryId, ref, prefix, limit, cursor}) {
+      const connection = await getConnection(connectionId);
+      if (connection.workspaceId !== workspaceId) {
+        throw new IntegrationConnectionWorkspaceMismatchError(connectionId);
+      }
+      const sourceControl = registry.getAdapter(connection.provider, 'source_control');
+
+      return await sourceControl.listFiles({
+        connection,
+        externalRepositoryId,
+        ref,
+        prefix,
+        limit,
+        cursor,
+      });
+    },
+
+    async fetchFile({workspaceId, connectionId, externalRepositoryId, ref, path}) {
+      const connection = await getConnection(connectionId);
+      if (connection.workspaceId !== workspaceId) {
+        throw new IntegrationConnectionWorkspaceMismatchError(connectionId);
+      }
+      const sourceControl = registry.getAdapter(connection.provider, 'source_control');
+
+      return await sourceControl.fetchFile({
+        connection,
+        externalRepositoryId,
+        ref,
+        path,
+      });
+    },
+
+    async createCheckoutSpec({workspaceId, connectionId, externalRepositoryId, ref, permissions}) {
+      const connection = await getConnection(connectionId);
+      if (connection.workspaceId !== workspaceId) {
+        throw new IntegrationConnectionWorkspaceMismatchError(connectionId);
+      }
+      const sourceControl = registry.getAdapter(connection.provider, 'source_control');
+      if (!sourceControl.createCheckoutSpec) {
+        throw new IntegrationCheckoutUnsupportedError(connection.provider);
+      }
+
+      return await sourceControl.createCheckoutSpec({
+        connection,
+        externalRepositoryId,
+        ref,
+        permissions,
+      });
+    },
+  };
+}

package/src/db/connections.test.ts

@@ -0,0 +1,296 @@
+import {ConnectionSlugConflictError} from '@shipfox/api-integration-core-dto';
+import {upsertGithubInstallation} from '@shipfox/api-integration-github';
+import {IntegrationConnectionAlreadyExistsError} from '#core/errors.js';
+import {
+  createIntegrationConnection,
+  deleteIntegrationConnection,
+  getIntegrationConnectionById,
+  listIntegrationConnections,
+  listIntegrationConnectionsByProvider,
+  resolveUniqueConnectionSlug,
+  updateIntegrationConnectionLifecycleStatus,
+  upsertIntegrationConnection,
+} from './connections.js';
+import {db} from './db.js';
+
+describe('integration connection queries', () => {
+  let workspaceId: string;
+
+  beforeEach(() => {
+    workspaceId = crypto.randomUUID();
+  });
+
+  it('upserts duplicate external connections for a workspace', async () => {
+    const first = await upsertIntegrationConnection({
+      workspaceId,
+      provider: 'gitea',
+      externalAccountId: 'gitea-owner',
+      slug: 'gitea_owner',
+      displayName: 'Gitea',
+    });
+
+    const second = await upsertIntegrationConnection({
+      workspaceId,
+      provider: 'gitea',
+      externalAccountId: 'gitea-owner',
+      slug: 'debug_renamed',
+      displayName: 'Renamed Debug',
+    });
+
+    expect(second.id).toBe(first.id);
+    expect(second.displayName).toBe('Renamed Debug');
+    expect(second.slug).toBe('gitea_owner');
+  });
+
+  it('allows multiple same-provider connections when external account differs', async () => {
+    await upsertIntegrationConnection({
+      workspaceId,
+      provider: 'gitea',
+      externalAccountId: 'debug-1',
+      slug: 'debug_1',
+      displayName: 'Debug One',
+    });
+    await upsertIntegrationConnection({
+      workspaceId,
+      provider: 'gitea',
+      externalAccountId: 'debug-2',
+      slug: 'debug_2',
+      displayName: 'Debug Two',
+    });
+
+    const result = await listIntegrationConnections({workspaceId});
+
+    expect(result).toHaveLength(2);
+  });
+
+  it('resolves a unique slug in workspace scope', async () => {
+    await upsertIntegrationConnection({
+      workspaceId,
+      provider: 'gitea',
+      externalAccountId: 'debug-1',
+      slug: 'gitea_owner',
+      displayName: 'Debug One',
+    });
+    await upsertIntegrationConnection({
+      workspaceId,
+      provider: 'github',
+      externalAccountId: 'debug-2',
+      slug: 'debug_2',
+      displayName: 'Debug Two',
+    });
+
+    const result = await resolveUniqueConnectionSlug({
+      workspaceId,
+      provider: 'gitea',
+      externalAccountId: 'debug-3',
+      baseSlug: 'debug',
+    });
+
+    expect(result).toBe('debug');
+  });
+
+  it('keeps the existing slug when resolving a reconnect', async () => {
+    await upsertIntegrationConnection({
+      workspaceId,
+      provider: 'sentry',
+      externalAccountId: 'install-uuid',
+      slug: 'sentry_prod',
+      displayName: 'Sentry',
+    });
+
+    const result = await resolveUniqueConnectionSlug({
+      workspaceId,
+      provider: 'sentry',
+      externalAccountId: 'install-uuid',
+      baseSlug: 'sentry_renamed',
+    });
+
+    expect(result).toBe('sentry_prod');
+  });
+
+  it('creates a connection without upserting duplicates', async () => {
+    const first = await createIntegrationConnection({
+      workspaceId,
+      provider: 'webhook',
+      externalAccountId: 'stripe',
+      slug: 'stripe',
+      displayName: 'Stripe',
+    });
+
+    const result = createIntegrationConnection({
+      workspaceId,
+      provider: 'webhook',
+      externalAccountId: 'stripe',
+      slug: 'stripe_renamed',
+      displayName: 'Renamed Stripe',
+    });
+
+    await expect(result).rejects.toBeInstanceOf(IntegrationConnectionAlreadyExistsError);
+    const connections = await listIntegrationConnections({workspaceId});
+    expect(connections).toHaveLength(1);
+    expect(connections[0]?.id).toBe(first.id);
+    expect(connections[0]?.displayName).toBe('Stripe');
+  });
+
+  it('reports slug collisions separately from duplicate external accounts', async () => {
+    await createIntegrationConnection({
+      workspaceId,
+      provider: 'webhook',
+      externalAccountId: 'stripe',
+      slug: 'stripe',
+      displayName: 'Stripe',
+    });
+
+    const result = createIntegrationConnection({
+      workspaceId,
+      provider: 'webhook',
+      externalAccountId: 'stripe-prod',
+      slug: 'stripe',
+      displayName: 'Stripe prod',
+    });
+
+    await expect(result).rejects.toBeInstanceOf(ConnectionSlugConflictError);
+  });
+
+  it('lists workspace connections across all lifecycle statuses', async () => {
+    await upsertIntegrationConnection({
+      workspaceId,
+      provider: 'gitea',
+      externalAccountId: 'gitea-owner',
+      slug: 'gitea_owner',
+      displayName: 'Gitea',
+    });
+    await upsertIntegrationConnection({
+      workspaceId,
+      provider: 'github',
+      externalAccountId: 'team-1',
+      slug: 'github_team_1',
+      displayName: 'GitHub',
+    });
+    await upsertIntegrationConnection({
+      workspaceId,
+      provider: 'github',
+      externalAccountId: 'installation-1',
+      slug: 'github_installation_1',
+      displayName: 'GitHub',
+      lifecycleStatus: 'disabled',
+    });
+
+    const result = await listIntegrationConnections({workspaceId});
+
+    expect(result.map((connection) => [connection.provider, connection.lifecycleStatus])).toEqual([
+      ['gitea', 'active'],
+      ['github', 'active'],
+      ['github', 'disabled'],
+    ]);
+  });
+
+  it('lists connections for a provider across all workspaces', async () => {
+    const otherWorkspaceId = crypto.randomUUID();
+    const debugA = await upsertIntegrationConnection({
+      workspaceId,
+      provider: 'gitea',
+      externalAccountId: 'gitea-owner',
+      slug: 'gitea_owner',
+      displayName: 'Gitea',
+    });
+    const debugB = await upsertIntegrationConnection({
+      workspaceId: otherWorkspaceId,
+      provider: 'gitea',
+      externalAccountId: 'gitea-owner',
+      slug: 'gitea_owner',
+      displayName: 'Gitea',
+    });
+    const github = await upsertIntegrationConnection({
+      workspaceId,
+      provider: 'github',
+      externalAccountId: 'gh-1',
+      slug: 'github_gh_1',
+      displayName: 'GitHub',
+    });
+
+    const result = await listIntegrationConnectionsByProvider({provider: 'gitea'});
+
+    const ids = result.map((connection) => connection.id);
+    expect(result.every((connection) => connection.provider === 'gitea')).toBe(true);
+    expect(ids).toEqual(expect.arrayContaining([debugA.id, debugB.id]));
+    expect(ids).not.toContain(github.id);
+  });
+
+  it('updates a connection lifecycle status and returns the mapped connection', async () => {
+    const connection = await upsertIntegrationConnection({
+      workspaceId,
+      provider: 'sentry',
+      externalAccountId: 'install-uuid',
+      slug: 'sentry_install_uuid',
+      displayName: 'Sentry acme',
+    });
+
+    const updated = await updateIntegrationConnectionLifecycleStatus({
+      id: connection.id,
+      lifecycleStatus: 'disabled',
+    });
+
+    expect(updated?.lifecycleStatus).toBe('disabled');
+    const reloaded = await getIntegrationConnectionById(connection.id);
+    expect(reloaded?.lifecycleStatus).toBe('disabled');
+  });
+
+  it('returns undefined when updating the lifecycle status of an unknown connection', async () => {
+    const result = await updateIntegrationConnectionLifecycleStatus({
+      id: crypto.randomUUID(),
+      lifecycleStatus: 'disabled',
+    });
+
+    expect(result).toBeUndefined();
+  });
+
+  it('deletes a connection and reports whether a row was removed', async () => {
+    const connection = await upsertIntegrationConnection({
+      workspaceId,
+      provider: 'webhook',
+      externalAccountId: 'stripe',
+      slug: 'stripe',
+      displayName: 'Stripe',
+    });
+
+    const deleted = await deleteIntegrationConnection({id: connection.id});
+    const deletedAgain = await deleteIntegrationConnection({id: connection.id});
+
+    expect(deleted).toBe(true);
+    expect(deletedAgain).toBe(false);
+    expect(await getIntegrationConnectionById(connection.id)).toBeUndefined();
+  });
+
+  it('rolls back a connection when provider-specific installation persistence fails', async () => {
+    const result = db().transaction(async (tx) => {
+      const connection = await upsertIntegrationConnection(
+        {
+          workspaceId,
+          provider: 'github',
+          externalAccountId: '123',
+          slug: 'github_123',
+          displayName: 'GitHub shipfox',
+        },
+        {tx},
+      );
+
+      await upsertGithubInstallation(
+        {
+          connectionId: connection.id,
+          installationId: '123',
+          accountLogin: null as unknown as string,
+          accountType: 'Organization',
+          repositorySelection: 'all',
+          latestEvent: {id: 123},
+        },
+        {tx},
+      );
+    });
+
+    await expect(result).rejects.toThrow();
+
+    const connections = await listIntegrationConnections({workspaceId});
+    expect(connections).toHaveLength(0);
+  });
+});