@shipfox/api-integration-gitea 2.0.0

package/src/db/connections.ts

@@ -0,0 +1,80 @@
+import {eq} from 'drizzle-orm';
+import {GiteaOrgAlreadyLinkedError} from '#core/errors.js';
+import {db} from './db.js';
+import {giteaConnections, toGiteaConnection} from './schema/connections.js';
+
+export interface GiteaConnection {
+  id: string;
+  connectionId: string;
+  org: string;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+export interface UpsertGiteaConnectionParams {
+  connectionId: string;
+  org: string;
+}
+
+type GiteaDb = ReturnType<typeof db>;
+type GiteaTx = Parameters<Parameters<GiteaDb['transaction']>[0]>[0];
+
+export async function upsertGiteaConnection(
+  params: UpsertGiteaConnectionParams,
+  options: {tx?: unknown} = {},
+): Promise<GiteaConnection> {
+  const executor = (options.tx ?? db()) as GiteaDb | GiteaTx;
+  const now = new Date();
+  const [row] = await executor
+    .insert(giteaConnections)
+    .values({
+      connectionId: params.connectionId,
+      org: params.org,
+    })
+    .onConflictDoUpdate({
+      target: giteaConnections.org,
+      // TOCTOU guard: only (re)point this org at the connection that already
+      // owns it. A concurrent connect of the same org to a different workspace
+      // inserts its own connection row, so its connectionId differs here; the
+      // predicate is false, Postgres updates nothing, and the empty RETURNING
+      // below rolls the losing transaction back instead of silently repointing
+      // the org (cross-tenant connection takeover).
+      setWhere: eq(giteaConnections.connectionId, params.connectionId),
+      set: {
+        connectionId: params.connectionId,
+        updatedAt: now,
+      },
+    })
+    .returning();
+
+  if (!row) throw new GiteaOrgAlreadyLinkedError(params.org);
+  return toGiteaConnection(row);
+}
+
+export async function getGiteaConnectionByOrg(
+  org: string,
+  options: {tx?: unknown} = {},
+): Promise<GiteaConnection | undefined> {
+  const executor = (options.tx ?? db()) as GiteaDb | GiteaTx;
+  const rows = await executor
+    .select()
+    .from(giteaConnections)
+    .where(eq(giteaConnections.org, org))
+    .limit(1);
+  const row = rows[0];
+  if (!row) return undefined;
+  return toGiteaConnection(row);
+}
+
+export async function getGiteaConnectionByConnectionId(
+  connectionId: string,
+): Promise<GiteaConnection | undefined> {
+  const rows = await db()
+    .select()
+    .from(giteaConnections)
+    .where(eq(giteaConnections.connectionId, connectionId))
+    .limit(1);
+  const row = rows[0];
+  if (!row) return undefined;
+  return toGiteaConnection(row);
+}

package/src/db/db.ts

@@ -0,0 +1,18 @@
+import {drizzle, type NodePgDatabase} from '@shipfox/node-drizzle';
+import {pgClient} from '@shipfox/node-postgres';
+import {giteaConnections} from './schema/connections.js';
+
+export const schema = {
+  giteaConnections,
+};
+
+let _db: NodePgDatabase<typeof schema> | undefined;
+
+export function db() {
+  if (!_db) _db = drizzle(pgClient(), {schema});
+  return _db;
+}
+
+export function closeDb(): void {
+  _db = undefined;
+}

package/src/db/migrations.ts

@@ -0,0 +1,4 @@
+import {dirname, resolve} from 'node:path';
+import {fileURLToPath} from 'node:url';
+
+export const migrationsPath = resolve(dirname(fileURLToPath(import.meta.url)), '../../drizzle');

package/src/db/schema/common.ts

@@ -0,0 +1,3 @@
+import {pgTableCreator} from 'drizzle-orm/pg-core';
+
+export const pgTable = pgTableCreator((name) => `integrations_gitea_${name}`);

package/src/db/schema/connections.ts

@@ -0,0 +1,32 @@
+import {uuidv7PrimaryKey} from '@shipfox/node-drizzle';
+import {text, timestamp, uniqueIndex, uuid} from 'drizzle-orm/pg-core';
+import type {GiteaConnection} from '#db/connections.js';
+import {pgTable} from './common.js';
+
+export const giteaConnections = pgTable(
+  'connections',
+  {
+    id: uuidv7PrimaryKey(),
+    connectionId: uuid('connection_id').notNull(),
+    org: text('org').notNull(),
+    createdAt: timestamp('created_at', {withTimezone: true}).notNull().defaultNow(),
+    updatedAt: timestamp('updated_at', {withTimezone: true}).notNull().defaultNow(),
+  },
+  (table) => [
+    uniqueIndex('integrations_gitea_connections_connection_unique').on(table.connectionId),
+    uniqueIndex('integrations_gitea_connections_org_unique').on(table.org),
+  ],
+);
+
+export type GiteaConnectionDb = typeof giteaConnections.$inferSelect;
+export type GiteaConnectionCreateDb = typeof giteaConnections.$inferInsert;
+
+export function toGiteaConnection(row: GiteaConnectionDb): GiteaConnection {
+  return {
+    id: row.id,
+    connectionId: row.connectionId,
+    org: row.org,
+    createdAt: row.createdAt,
+    updatedAt: row.updatedAt,
+  };
+}

package/src/index.test.ts

@@ -0,0 +1,23 @@
+import {createGiteaIntegrationProvider, GiteaSourceControlProvider} from '#index.js';
+
+describe('createGiteaIntegrationProvider', () => {
+  it('exposes the gitea source-control adapter and the connection + webhook route groups', () => {
+    const provider = createGiteaIntegrationProvider({
+      getExistingGiteaConnection: vi.fn(() => Promise.resolve(undefined)),
+      connectGiteaConnection: vi.fn() as never,
+      coreDb: vi.fn() as never,
+      publishSourcePush: vi.fn() as never,
+      recordDeliveryOnly: vi.fn() as never,
+      getIntegrationConnectionById: vi.fn() as never,
+    });
+
+    expect(provider.provider).toBe('gitea');
+    expect(provider.displayName).toBe('Gitea');
+    expect(provider.adapters.source_control).toBeInstanceOf(GiteaSourceControlProvider);
+    expect(provider.routes).toHaveLength(2);
+    expect(provider.routes.map((group) => group.prefix)).toEqual([
+      '/integrations/gitea',
+      '/webhooks/integrations/gitea',
+    ]);
+  });
+});

package/src/index.ts

@@ -0,0 +1,83 @@
+import type {
+  GetIntegrationConnectionByIdFn,
+  IntegrationConnection,
+  PublishSourcePushFn,
+  RecordDeliveryOnlyFn,
+} from '@shipfox/api-integration-core-dto';
+import {giteaProviderKind} from '@shipfox/api-integration-gitea-dto';
+import type {NodePgDatabase} from 'drizzle-orm/node-postgres';
+import {createGiteaApiClient, type GiteaApiClient} from '#api/client.js';
+import type {ConnectGiteaConnectionInput} from '#core/connect.js';
+import {giteaConnectionExternalUrl} from '#core/connection-url.js';
+import {GiteaSourceControlProvider} from '#core/source-control.js';
+import {closeDb, db} from '#db/db.js';
+import {migrationsPath} from '#db/migrations.js';
+import {createGiteaConnectionRoutes} from '#presentation/routes/connections.js';
+import {createGiteaWebhookRoutes} from '#presentation/routes/webhooks.js';
+
+export type {
+  GiteaApiClient,
+  GiteaFileContent,
+  GiteaRepository,
+  GiteaRepositoryPage,
+  GiteaTree,
+  GiteaTreeBlob,
+} from '#api/client.js';
+export {createGiteaApiClient} from '#api/client.js';
+export type {ConnectGiteaConnectionInput} from '#core/connect.js';
+export {handleGiteaConnect} from '#core/connect.js';
+export {
+  GiteaIntegrationProviderError,
+  GiteaOrgAlreadyLinkedError,
+  GiteaOrganizationNotFoundError,
+} from '#core/errors.js';
+export {GiteaSourceControlProvider} from '#core/source-control.js';
+export type {GiteaConnection, UpsertGiteaConnectionParams} from '#db/connections.js';
+export {
+  getGiteaConnectionByConnectionId,
+  getGiteaConnectionByOrg,
+  upsertGiteaConnection,
+} from '#db/connections.js';
+export {closeDb, db, migrationsPath};
+
+export interface CreateGiteaIntegrationProviderOptions {
+  gitea?: GiteaApiClient | undefined;
+  getExistingGiteaConnection: (input: {
+    org: string;
+  }) => Promise<IntegrationConnection<'gitea'> | undefined>;
+  connectGiteaConnection: (
+    input: ConnectGiteaConnectionInput,
+  ) => Promise<IntegrationConnection<'gitea'>>;
+  coreDb: () => NodePgDatabase<Record<string, unknown>>;
+  publishSourcePush: PublishSourcePushFn;
+  recordDeliveryOnly: RecordDeliveryOnlyFn;
+  getIntegrationConnectionById: GetIntegrationConnectionByIdFn;
+}
+
+export function createGiteaIntegrationProvider(options: CreateGiteaIntegrationProviderOptions) {
+  const gitea = options.gitea ?? createGiteaApiClient();
+
+  return {
+    provider: giteaProviderKind,
+    displayName: 'Gitea',
+    adapters: {
+      source_control: new GiteaSourceControlProvider(gitea),
+    },
+    connectionExternalUrl(connection: {externalAccountId: string}): Promise<string | undefined> {
+      return Promise.resolve(giteaConnectionExternalUrl(connection.externalAccountId));
+    },
+    routes: [
+      createGiteaConnectionRoutes({
+        gitea,
+        getExistingGiteaConnection: options.getExistingGiteaConnection,
+        connectGiteaConnection: options.connectGiteaConnection,
+      }),
+      createGiteaWebhookRoutes({
+        coreDb: options.coreDb,
+        publishSourcePush: options.publishSourcePush,
+        recordDeliveryOnly: options.recordDeliveryOnly,
+        getIntegrationConnectionById: options.getIntegrationConnectionById,
+      }),
+    ],
+  };
+}

package/src/presentation/dto/integrations.ts

@@ -0,0 +1,14 @@
+import {
+  type IntegrationConnection,
+  toIntegrationConnectionDto as toCoreIntegrationConnectionDto,
+} from '@shipfox/api-integration-core-dto';
+
+export function toIntegrationConnectionDto(
+  connection: IntegrationConnection<'gitea'>,
+  options: {externalUrl?: string | undefined} = {},
+) {
+  return toCoreIntegrationConnectionDto(connection, {
+    capabilities: ['source_control'],
+    externalUrl: options.externalUrl,
+  });
+}

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

@@ -0,0 +1,200 @@
+import {
+  AUTH_USER,
+  buildUserContext,
+  setUserContext,
+  type UserContextMembership,
+} from '@shipfox/api-auth-context';
+import {
+  ConnectionSlugConflictError,
+  type IntegrationConnection,
+} from '@shipfox/api-integration-core-dto';
+import {type AuthMethod, ClientError, closeApp, createApp} from '@shipfox/node-fastify';
+import type {FastifyInstance, FastifyRequest} from 'fastify';
+import type {GiteaApiClient} from '#api/client.js';
+import type {ConnectGiteaConnectionInput} from '#core/connect.js';
+import {createGiteaIntegrationProvider} from '#index.js';
+
+let authenticatedMemberships: UserContextMembership[] = [];
+
+const fakeUserAuth: AuthMethod = {
+  name: AUTH_USER,
+  authenticate: (request: FastifyRequest) => {
+    if (request.headers.authorization !== 'Bearer user') {
+      throw new ClientError('Invalid user token', 'unauthorized', {status: 401});
+    }
+
+    setUserContext(
+      request,
+      buildUserContext({
+        userId: 'user-1',
+        email: 'user@example.com',
+        memberships: authenticatedMemberships,
+      }),
+    );
+    return Promise.resolve();
+  },
+};
+
+function giteaClient(overrides: Partial<GiteaApiClient> = {}): GiteaApiClient {
+  return {
+    listOrgRepositories: vi.fn(() => Promise.reject(new Error('not used'))),
+    getRepository: vi.fn(() => Promise.reject(new Error('not used'))),
+    resolveRef: vi.fn(() => Promise.reject(new Error('not used'))),
+    listTree: vi.fn(() => Promise.reject(new Error('not used'))),
+    fetchFileContent: vi.fn(() => Promise.reject(new Error('not used'))),
+    organizationExists: vi.fn(() => Promise.resolve(true)),
+    ...overrides,
+  };
+}
+
+interface CreateTestAppOptions {
+  gitea?: GiteaApiClient;
+  existingConnection?: IntegrationConnection<'gitea'> | undefined;
+  connectGiteaConnection?:
+    | ((input: ConnectGiteaConnectionInput) => Promise<IntegrationConnection<'gitea'>>)
+    | undefined;
+}
+
+async function createTestApp(options: CreateTestAppOptions = {}): Promise<FastifyInstance> {
+  const provider = createGiteaIntegrationProvider({
+    gitea: options.gitea ?? giteaClient(),
+    getExistingGiteaConnection: vi.fn(() => Promise.resolve(options.existingConnection)),
+    connectGiteaConnection:
+      options.connectGiteaConnection ??
+      vi.fn((input: ConnectGiteaConnectionInput) => {
+        const connection: IntegrationConnection<'gitea'> = {
+          id: crypto.randomUUID(),
+          workspaceId: input.workspaceId,
+          provider: 'gitea',
+          externalAccountId: input.org,
+          slug: 'gitea_shipfox',
+          displayName: input.displayName,
+          lifecycleStatus: 'active',
+          createdAt: new Date(),
+          updatedAt: new Date(),
+        };
+
+        return Promise.resolve(connection);
+      }),
+    // Provider-level mounting includes webhook routes; these tests exercise only connections.
+    coreDb: vi.fn() as never,
+    publishSourcePush: vi.fn() as never,
+    recordDeliveryOnly: vi.fn() as never,
+    getIntegrationConnectionById: vi.fn() as never,
+  });
+  const app = await createApp({
+    auth: [fakeUserAuth],
+    routes: provider.routes,
+    swagger: false,
+  });
+  await app.ready();
+  return app;
+}
+
+describe('Gitea connection routes', () => {
+  beforeEach(async () => {
+    authenticatedMemberships = [];
+    await closeApp();
+  });
+
+  afterEach(async () => {
+    await closeApp();
+  });
+
+  it('requires auth to connect an org', async () => {
+    const app = await createTestApp();
+
+    const res = await app.inject({
+      method: 'POST',
+      url: '/integrations/gitea/connections',
+      payload: {workspace_id: crypto.randomUUID(), org: 'shipfox'},
+    });
+
+    expect(res.statusCode).toBe(401);
+  });
+
+  it('connects an org and returns the connection DTO', async () => {
+    const app = await createTestApp();
+    const workspaceId = crypto.randomUUID();
+    authenticatedMemberships = [{workspaceId, role: 'admin'}];
+
+    const res = await app.inject({
+      method: 'POST',
+      url: '/integrations/gitea/connections',
+      headers: {authorization: 'Bearer user'},
+      payload: {workspace_id: workspaceId, org: 'shipfox'},
+    });
+
+    expect(res.statusCode).toBe(200);
+    expect(res.json().provider).toBe('gitea');
+    expect(res.json().external_account_id).toBe('shipfox');
+    expect(res.json().lifecycle_status).toBe('active');
+    expect(res.json().external_url).toBe('https://gitea.example.com/shipfox');
+  });
+
+  it('returns 404 when the org does not exist', async () => {
+    const app = await createTestApp({
+      gitea: giteaClient({organizationExists: vi.fn(() => Promise.resolve(false))}),
+    });
+    const workspaceId = crypto.randomUUID();
+    authenticatedMemberships = [{workspaceId, role: 'admin'}];
+
+    const res = await app.inject({
+      method: 'POST',
+      url: '/integrations/gitea/connections',
+      headers: {authorization: 'Bearer user'},
+      payload: {workspace_id: workspaceId, org: 'ghost'},
+    });
+
+    expect(res.statusCode).toBe(404);
+    expect(res.json().code).toBe('gitea-organization-not-found');
+  });
+
+  it('returns 409 when the org is already linked to another workspace', async () => {
+    const workspaceId = crypto.randomUUID();
+    authenticatedMemberships = [{workspaceId, role: 'admin'}];
+    const app = await createTestApp({
+      existingConnection: {
+        id: crypto.randomUUID(),
+        workspaceId: crypto.randomUUID(),
+        provider: 'gitea',
+        externalAccountId: 'shipfox',
+        slug: 'gitea_shipfox',
+        displayName: 'Gitea shipfox',
+        lifecycleStatus: 'active',
+        createdAt: new Date(),
+        updatedAt: new Date(),
+      },
+    });
+
+    const res = await app.inject({
+      method: 'POST',
+      url: '/integrations/gitea/connections',
+      headers: {authorization: 'Bearer user'},
+      payload: {workspace_id: workspaceId, org: 'shipfox'},
+    });
+
+    expect(res.statusCode).toBe(409);
+    expect(res.json().code).toBe('gitea-org-already-linked');
+  });
+
+  it('returns 409 when connection slug allocation conflicts repeatedly', async () => {
+    const workspaceId = crypto.randomUUID();
+    authenticatedMemberships = [{workspaceId, role: 'admin'}];
+    const app = await createTestApp({
+      connectGiteaConnection: vi.fn(() =>
+        Promise.reject(new ConnectionSlugConflictError(new Error('duplicate slug'))),
+      ),
+    });
+
+    const res = await app.inject({
+      method: 'POST',
+      url: '/integrations/gitea/connections',
+      headers: {authorization: 'Bearer user'},
+      payload: {workspace_id: workspaceId, org: 'shipfox'},
+    });
+
+    expect(res.statusCode).toBe(409);
+    expect(res.json().code).toBe('slug-conflict');
+  });
+});

package/src/presentation/routes/connections.ts

@@ -0,0 +1,63 @@
+import {AUTH_USER, requireWorkspaceAccess} from '@shipfox/api-auth-context';
+import type {IntegrationConnection} from '@shipfox/api-integration-core-dto';
+import {
+  createGiteaConnectionBodySchema,
+  createGiteaConnectionResponseSchema,
+} from '@shipfox/api-integration-gitea-dto';
+import {defineRoute, type RouteGroup} from '@shipfox/node-fastify';
+import type {GiteaApiClient} from '#api/client.js';
+import {type ConnectGiteaConnectionInput, handleGiteaConnect} from '#core/connect.js';
+import {giteaConnectionExternalUrl} from '#core/connection-url.js';
+import {toIntegrationConnectionDto} from '#presentation/dto/integrations.js';
+import {giteaRouteErrorHandler} from './errors.js';
+
+export interface CreateGiteaConnectionRoutesOptions {
+  gitea: GiteaApiClient;
+  getExistingGiteaConnection: (input: {
+    org: string;
+  }) => Promise<IntegrationConnection<'gitea'> | undefined>;
+  connectGiteaConnection: (
+    input: ConnectGiteaConnectionInput,
+  ) => Promise<IntegrationConnection<'gitea'>>;
+}
+
+export function createGiteaConnectionRoutes({
+  gitea,
+  getExistingGiteaConnection,
+  connectGiteaConnection,
+}: CreateGiteaConnectionRoutesOptions): RouteGroup {
+  const createConnectionRoute = defineRoute({
+    method: 'POST',
+    path: '/connections',
+    auth: AUTH_USER,
+    description: 'Connect a Gitea organization to a workspace.',
+    schema: {
+      body: createGiteaConnectionBodySchema,
+      response: {
+        200: createGiteaConnectionResponseSchema,
+      },
+    },
+    errorHandler: giteaRouteErrorHandler,
+    handler: async (request) => {
+      const {workspace_id: workspaceId, org} = request.body;
+
+      requireWorkspaceAccess({request, workspaceId});
+      const connection = await handleGiteaConnect({
+        gitea,
+        workspaceId,
+        org,
+        getExistingGiteaConnection,
+        connectGiteaConnection,
+      });
+
+      return toIntegrationConnectionDto(connection, {
+        externalUrl: giteaConnectionExternalUrl(connection.externalAccountId),
+      });
+    },
+  });
+
+  return {
+    prefix: '/integrations/gitea',
+    routes: [createConnectionRoute],
+  };
+}

package/src/presentation/routes/errors.ts

@@ -0,0 +1,35 @@
+import {
+  ConnectionSlugConflictError,
+  type IntegrationProviderErrorReason,
+} from '@shipfox/api-integration-core-dto';
+import {ClientError} from '@shipfox/node-fastify';
+import {
+  GiteaIntegrationProviderError,
+  GiteaOrgAlreadyLinkedError,
+  GiteaOrganizationNotFoundError,
+} from '#core/errors.js';
+
+function providerStatus(reason: IntegrationProviderErrorReason): number {
+  if (reason === 'rate-limited') return 429;
+  if (reason === 'timeout' || reason === 'provider-unavailable') return 503;
+  return 422;
+}
+
+export function giteaRouteErrorHandler(error: unknown): never {
+  if (error instanceof GiteaOrganizationNotFoundError) {
+    throw new ClientError(error.message, 'gitea-organization-not-found', {status: 404});
+  }
+  if (error instanceof GiteaOrgAlreadyLinkedError) {
+    throw new ClientError(error.message, 'gitea-org-already-linked', {status: 409});
+  }
+  if (error instanceof ConnectionSlugConflictError) {
+    throw new ClientError(error.message, 'slug-conflict', {status: 409});
+  }
+  if (error instanceof GiteaIntegrationProviderError) {
+    throw new ClientError(error.message, error.reason, {
+      details: {retry_after_seconds: error.retryAfterSeconds},
+      status: providerStatus(error.reason),
+    });
+  }
+  throw error;
+}