@shipfox/api-projects 9.3.0 → 10.1.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shipfox/api-projects",
   "license": "MIT",
-  "version": "9.3.0",
+  "version": "10.1.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ShipfoxHQ/shipfox.git",
@@ -21,13 +21,14 @@
     "@temporalio/workflow": "1.18.1",
     "drizzle-orm": "^0.45.2",
     "zod": "^4.4.3",
-    "@shipfox/api-auth-context": "9.3.0",
+    "@shipfox/api-auth-dto": "10.1.0",
+    "@shipfox/api-auth-context": "10.1.0",
     "@shipfox/api-integration-core-dto": "9.0.2",
-    "@shipfox/api-projects-dto": "9.2.0",
+    "@shipfox/api-projects-dto": "10.1.0",
     "@shipfox/inter-module": "0.2.2",
     "@shipfox/node-drizzle": "0.3.4",
-    "@shipfox/node-fastify": "0.3.4",
-    "@shipfox/node-module": "1.0.3",
+    "@shipfox/node-fastify": "0.4.0",
+    "@shipfox/node-module": "1.0.4",
     "@shipfox/node-opentelemetry": "0.6.3",
     "@shipfox/node-outbox": "0.2.6",
     "@shipfox/node-postgres": "0.4.4",

package/src/db/index.ts

@@ -7,8 +7,11 @@ export {
   recordIntegrationEventForProject,
 } from './integration-event-dedup.js';
 export type {
+  AdminProjectSummary,
   CreateProjectParams,
   GetProjectBySourceParams,
+  ListAdminProjectsParams,
+  ListAdminProjectsResult,
   ListProjectsParams,
   ListProjectsResult,
 } from './projects.js';
@@ -17,6 +20,8 @@ export {
   getProjectById,
   getProjectBySource,
   getProjectCount,
+  getWorkspaceProjectCounts,
+  listAdminProjects,
   listProjects,
   requireProjectForWorkspace,
 } from './projects.js';

package/src/db/projects.test.ts

@@ -1,5 +1,5 @@
 import {projectFactory} from '#test/index.js';
-import {getProjectCount} from './projects.js';
+import {getProjectCount, getWorkspaceProjectCounts} from './projects.js';
 
 describe('getProjectCount', () => {
   it('reports the current project count', async () => {
@@ -19,4 +19,12 @@ describe('getProjectCount', () => {
 
     expect(after - before).toBe(2);
   });
+
+  it('returns zero for workspaces without projects', async () => {
+    const workspaceId = crypto.randomUUID();
+
+    const counts = await getWorkspaceProjectCounts({workspaceIds: [workspaceId]});
+
+    expect(counts).toEqual([{workspaceId, count: 0}]);
+  });
 });

package/src/db/projects.ts

@@ -1,4 +1,4 @@
-import {and, count, desc, eq, ilike, lt, or, type SQL} from 'drizzle-orm';
+import {and, count, desc, eq, ilike, inArray, lt, or, type SQL} from 'drizzle-orm';
 import type {Project} from '#core/entities/project.js';
 import {ProjectAlreadyExistsError, ProjectNotFoundError} from '#core/errors.js';
 import {recordProjectCreated} from '#metrics/instance.js';
@@ -33,11 +33,28 @@ export interface ListProjectsResult {
   nextCursor: ProjectCursor | null;
 }
 
-function cursorWhere(params: ListProjectsParams): SQL | undefined {
-  if (!params.cursor) return undefined;
+export type AdminProjectSummary = Pick<
+  Project,
+  'id' | 'workspaceId' | 'name' | 'createdAt' | 'updatedAt'
+>;
+
+export interface ListAdminProjectsParams {
+  limit: number;
+  cursor?: ProjectCursor | undefined;
+  projectId?: string | undefined;
+  search?: string | undefined;
+}
+
+export interface ListAdminProjectsResult {
+  projects: AdminProjectSummary[];
+  nextCursor: ProjectCursor | null;
+}
+
+function cursorWhere(cursor: ProjectCursor | undefined): SQL | undefined {
+  if (!cursor) return undefined;
   return or(
-    lt(projects.createdAt, params.cursor.createdAt),
-    and(eq(projects.createdAt, params.cursor.createdAt), lt(projects.id, params.cursor.id)),
+    lt(projects.createdAt, cursor.createdAt),
+    and(eq(projects.createdAt, cursor.createdAt), lt(projects.id, cursor.id)),
   );
 }
 
@@ -129,7 +146,7 @@ export async function requireProjectForWorkspace(params: {
 
 export async function listProjects(params: ListProjectsParams): Promise<ListProjectsResult> {
   const conditions = [eq(projects.workspaceId, params.workspaceId)];
-  const cursorCondition = cursorWhere(params);
+  const cursorCondition = cursorWhere(params.cursor);
   if (cursorCondition) conditions.push(cursorCondition);
   if (params.search) {
     conditions.push(ilike(projects.name, `%${escapeIlikePattern(params.search)}%`));
@@ -152,7 +169,57 @@ export async function listProjects(params: ListProjectsParams): Promise<ListProj
   };
 }
 
+export async function listAdminProjects(
+  params: ListAdminProjectsParams,
+): Promise<ListAdminProjectsResult> {
+  const conditions: SQL[] = [];
+  const cursorCondition = cursorWhere(params.cursor);
+  if (cursorCondition) conditions.push(cursorCondition);
+  if (params.projectId) conditions.push(eq(projects.id, params.projectId));
+  if (params.search) {
+    conditions.push(ilike(projects.name, `%${escapeIlikePattern(params.search)}%`));
+  }
+
+  const rows = await db()
+    .select({
+      id: projects.id,
+      workspaceId: projects.workspaceId,
+      name: projects.name,
+      createdAt: projects.createdAt,
+      updatedAt: projects.updatedAt,
+    })
+    .from(projects)
+    .where(conditions.length > 0 ? and(...conditions) : undefined)
+    .orderBy(desc(projects.createdAt), desc(projects.id))
+    .limit(params.limit + 1);
+
+  const hasMore = rows.length > params.limit;
+  const pageRows = hasMore ? rows.slice(0, params.limit) : rows;
+  const last = pageRows.at(-1);
+
+  return {
+    projects: pageRows,
+    nextCursor: hasMore && last ? {createdAt: last.createdAt, id: last.id} : null,
+  };
+}
+
 export async function getProjectCount(): Promise<number> {
   const [row] = await db().select({value: count()}).from(projects);
   return row?.value ?? 0;
 }
+
+export async function getWorkspaceProjectCounts(params: {
+  workspaceIds: string[];
+}): Promise<Array<{workspaceId: string; count: number}>> {
+  const rows = await db()
+    .select({workspaceId: projects.workspaceId, count: count()})
+    .from(projects)
+    .where(inArray(projects.workspaceId, params.workspaceIds))
+    .groupBy(projects.workspaceId);
+
+  const countsByWorkspace = new Map(rows.map((row) => [row.workspaceId, Number(row.count)]));
+  return params.workspaceIds.map((workspaceId) => ({
+    workspaceId,
+    count: countsByWorkspace.get(workspaceId) ?? 0,
+  }));
+}

package/src/index.ts

@@ -1,5 +1,6 @@
 import {dirname, resolve} from 'node:path';
 import {fileURLToPath} from 'node:url';
+import type {AuthInterModuleClient} from '@shipfox/api-auth-dto/inter-module';
 import {
   INTEGRATION_SOURCE_COMMIT_PUSHED,
   type IntegrationsEventMap,
@@ -34,6 +35,7 @@ export {
   db,
   getProjectById,
   getProjectBySource,
+  getWorkspaceProjectCounts,
   listProjects,
   migrationsPath,
   projectsOutbox,
@@ -43,13 +45,17 @@ export {createProjectRoutes, requireProjectAccess} from '#presentation/index.js'
 
 export interface CreateProjectsModuleOptions {
   integrations: IntegrationsModuleClient;
+  auth: AuthInterModuleClient;
 }
 
-export function createProjectsModule({integrations}: CreateProjectsModuleOptions): ShipfoxModule {
+export function createProjectsModule({
+  integrations,
+  auth,
+}: CreateProjectsModuleOptions): ShipfoxModule {
   return {
     name: 'projects',
     database: {db, migrationsPath, databaseNamespace: 'projects'},
-    routes: createProjectRoutes(integrations),
+    routes: createProjectRoutes(integrations, auth),
     e2eRoutes: [projectsE2eRoutes],
     metrics: registerProjectsServiceMetrics,
     publishers: [{name: 'projects', table: projectsOutbox, db, eventSchemas: projectsEventSchemas}],

package/src/presentation/dto/index.ts

@@ -1 +1 @@
-export {toProjectDto} from './project.js';
+export {toAdminProjectSummaryDto, toProjectDto} from './project.js';

package/src/presentation/dto/project.ts

@@ -1,4 +1,5 @@
 import type {Project} from '#core/entities/index.js';
+import type {AdminProjectSummary} from '#db/projects.js';
 
 export function toProjectDto(project: Project) {
   return {
@@ -13,3 +14,14 @@ export function toProjectDto(project: Project) {
     updated_at: project.updatedAt.toISOString(),
   };
 }
+
+export function toAdminProjectSummaryDto(project: AdminProjectSummary) {
+  return {
+    id: project.id,
+    name: project.name,
+    status: 'active' as const,
+    workspace_id: project.workspaceId,
+    created_at: project.createdAt.toISOString(),
+    updated_at: project.updatedAt.toISOString(),
+  };
+}

package/src/presentation/inter-module.ts

@@ -4,7 +4,7 @@ import {
   defineInterModulePresentation,
   type InterModulePresentation,
 } from '@shipfox/inter-module';
-import {getProjectById} from '#db/projects.js';
+import {getProjectById, getWorkspaceProjectCounts} from '#db/projects.js';
 
 export function createProjectsInterModulePresentation(): InterModulePresentation<
   typeof projectsInterModuleContract
@@ -29,5 +29,8 @@ export function createProjectsInterModulePresentation(): InterModulePresentation
       }
       return {project};
     },
+    getWorkspaceProjectCounts: async ({workspaceIds}) => ({
+      counts: await getWorkspaceProjectCounts({workspaceIds}),
+    }),
   });
 }

package/src/presentation/routes/admin-projects.ts

@@ -0,0 +1,66 @@
+import {AUTH_USER, requireUserContext} from '@shipfox/api-auth-context';
+import {
+  type AuthInterModuleClient,
+  authInterModuleContract,
+} from '@shipfox/api-auth-dto/inter-module';
+import {
+  listAdminProjectsQuerySchema,
+  listAdminProjectsResponseSchema,
+} from '@shipfox/api-projects-dto';
+import {isInterModuleKnownError} from '@shipfox/inter-module';
+import {ClientError, defineRoute} from '@shipfox/node-fastify';
+import {listAdminProjects} from '#db/index.js';
+import {toAdminProjectSummaryDto} from '#presentation/dto/index.js';
+import {decodeProjectCursor, encodeProjectCursor} from './cursor.js';
+
+const minimumRole = 'admin-observer' as const;
+
+function translateAdminProjectRouteError(error: unknown): never {
+  if (
+    isInterModuleKnownError(authInterModuleContract.methods.requireAdminRole, error) &&
+    error.code === 'admin-role-required'
+  ) {
+    throw new ClientError('Administrator observer role required', 'forbidden', {
+      status: 403,
+      details: {required_role: error.details.requiredRole},
+    });
+  }
+
+  throw error;
+}
+
+export function createAdminProjectsRoute(auth: Pick<AuthInterModuleClient, 'requireAdminRole'>) {
+  return defineRoute({
+    method: 'GET',
+    path: '/',
+    auth: AUTH_USER,
+    description: 'List a bounded safe project summary for administrators.',
+    schema: {
+      querystring: listAdminProjectsQuerySchema,
+      response: {200: listAdminProjectsResponseSchema},
+    },
+    errorHandler: translateAdminProjectRouteError,
+    handler: async (request) => {
+      const actor = requireUserContext(request);
+      await auth.requireAdminRole({userId: actor.userId, minimumRole});
+
+      const {project_id: projectId, limit, cursor, search} = request.query;
+      const decodedCursor = decodeProjectCursor(cursor);
+      if (cursor && !decodedCursor) {
+        throw new ClientError('Invalid cursor', 'invalid-cursor', {status: 400});
+      }
+
+      const result = await listAdminProjects({
+        projectId,
+        limit,
+        cursor: decodedCursor,
+        search,
+      });
+
+      return {
+        projects: result.projects.map(toAdminProjectSummaryDto),
+        next_cursor: result.nextCursor ? encodeProjectCursor(result.nextCursor) : null,
+      };
+    },
+  });
+}

package/src/presentation/routes/index.ts

@@ -1,14 +1,23 @@
+import type {AuthInterModuleClient} from '@shipfox/api-auth-dto/inter-module';
 import type {IntegrationsModuleClient} from '@shipfox/api-integration-core-dto/inter-module';
 import type {RouteGroup} from '@shipfox/node-fastify';
+import {createAdminProjectsRoute} from './admin-projects.js';
 import {createProjectRoute} from './create-project.js';
 import {getProjectRoute} from './get-project.js';
 import {listProjectsRoute} from './list-projects.js';
 
-export function createProjectRoutes(integrations: IntegrationsModuleClient): RouteGroup[] {
+export function createProjectRoutes(
+  integrations: IntegrationsModuleClient,
+  auth: Pick<AuthInterModuleClient, 'requireAdminRole'>,
+): RouteGroup[] {
   return [
     {
       prefix: '/projects',
       routes: [createProjectRoute(integrations), listProjectsRoute, getProjectRoute],
     },
+    {
+      prefix: '/admin/projects',
+      routes: [createAdminProjectsRoute(auth)],
+    },
   ];
 }

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

@@ -4,6 +4,10 @@ import {
   setUserContext,
   type UserContextMembership,
 } from '@shipfox/api-auth-context';
+import {
+  type AuthInterModuleClient,
+  authInterModuleContract,
+} from '@shipfox/api-auth-dto/inter-module';
 import {
   type IntegrationsModuleClient,
   integrationsInterModuleContract,
@@ -12,6 +16,8 @@ import {createInterModuleKnownError} from '@shipfox/inter-module';
 import type {AuthMethod} from '@shipfox/node-fastify';
 import {closeApp, createApp} from '@shipfox/node-fastify';
 import type {FastifyInstance, FastifyRequest} from 'fastify';
+import type {Project} from '#core/entities/project.js';
+import {createProject} from '#db/projects.js';
 import {createProjectRoutes} from './index.js';
 
 let authenticatedMemberships: UserContextMembership[] = [];
@@ -37,6 +43,7 @@ describe('project routes', () => {
   let workspaceId: string;
   let sourceConnectionId: string;
   let integrations: Pick<IntegrationsModuleClient, 'resolveSourceRepository'>;
+  let auth: Pick<AuthInterModuleClient, 'requireAdminRole'>;
 
   beforeEach(async () => {
     await closeApp();
@@ -65,9 +72,12 @@ describe('project routes', () => {
         };
       }),
     };
+    auth = {
+      requireAdminRole: vi.fn().mockResolvedValue({role: 'admin-observer'}),
+    };
     app = await createApp({
       auth: [fakeUserAuth],
-      routes: createProjectRoutes(integrations as IntegrationsModuleClient),
+      routes: createProjectRoutes(integrations as IntegrationsModuleClient, auth),
       swagger: false,
     });
     await app.ready();
@@ -252,4 +262,166 @@ describe('project routes', () => {
     expect(res.statusCode).toBe(404);
     expect(res.json().code).toBe('source-connection-not-found');
   });
+
+  test('requires the administrator observer role for project lookup', async () => {
+    vi.mocked(auth.requireAdminRole).mockRejectedValueOnce(
+      createInterModuleKnownError(
+        authInterModuleContract.methods.requireAdminRole,
+        'admin-role-required',
+        {requiredRole: 'admin-observer'},
+      ),
+    );
+
+    const res = await app.inject({
+      method: 'GET',
+      url: '/admin/projects',
+      headers: {authorization: 'Bearer user'},
+    });
+
+    expect(res.statusCode).toBe(403);
+    expect(res.json()).toMatchObject({
+      code: 'forbidden',
+      details: {required_role: 'admin-observer'},
+    });
+    expect(auth.requireAdminRole).toHaveBeenCalledWith({
+      userId: 'user-1',
+      minimumRole: 'admin-observer',
+    });
+  });
+
+  test('rejects unbounded lookup parameters and malformed cursors', async () => {
+    const oversizedLimit = await app.inject({
+      method: 'GET',
+      url: '/admin/projects?limit=101',
+      headers: {authorization: 'Bearer user'},
+    });
+    expect(oversizedLimit.statusCode).toBe(400);
+
+    const oversizedSearch = await app.inject({
+      method: 'GET',
+      url: `/admin/projects?search=${'x'.repeat(101)}`,
+      headers: {authorization: 'Bearer user'},
+    });
+    expect(oversizedSearch.statusCode).toBe(400);
+
+    const malformedCursor = await app.inject({
+      method: 'GET',
+      url: '/admin/projects?cursor=not-a-cursor',
+      headers: {authorization: 'Bearer user'},
+    });
+    expect(malformedCursor.statusCode).toBe(400);
+    expect(malformedCursor.json().code).toBe('invalid-cursor');
+  });
+
+  test('returns a bounded redacted summary with checked search and cursor pagination', async () => {
+    const projects: Project[] = [];
+    for (const name of ['Platform', 'Runner', 'Running', 'Notifier']) {
+      projects.push(
+        await createProject({
+          workspaceId,
+          name,
+          sourceConnectionId: crypto.randomUUID(),
+          sourceExternalRepositoryId: `gitea:${name.toLowerCase()}`,
+        }),
+      );
+    }
+    const running = projects.find((project) => project.name === 'Running');
+    if (!running) throw new Error('Running project fixture was not created');
+
+    const searchRes = await app.inject({
+      method: 'GET',
+      url: '/admin/projects?search=runn&limit=1',
+      headers: {authorization: 'Bearer user'},
+    });
+
+    expect(searchRes.statusCode).toBe(200);
+    expect(searchRes.json()).toMatchObject({
+      projects: [
+        {
+          id: running.id,
+          name: 'Running',
+          status: 'active',
+          workspace_id: workspaceId,
+        },
+      ],
+      next_cursor: expect.any(String),
+    });
+    expect(searchRes.json().projects[0]).not.toHaveProperty('source');
+    expect(searchRes.json().projects[0]).not.toHaveProperty('source_connection_id');
+    expect(searchRes.json().projects[0]).not.toHaveProperty('source_external_repository_id');
+
+    const firstPage = await app.inject({
+      method: 'GET',
+      url: '/admin/projects?limit=1',
+      headers: {authorization: 'Bearer user'},
+    });
+    expect(firstPage.statusCode).toBe(200);
+    expect(firstPage.json().projects).toHaveLength(1);
+    expect(firstPage.json().next_cursor).toEqual(expect.any(String));
+
+    const secondPage = await app.inject({
+      method: 'GET',
+      url: `/admin/projects?limit=1&cursor=${encodeURIComponent(firstPage.json().next_cursor)}`,
+      headers: {authorization: 'Bearer user'},
+    });
+    expect(secondPage.statusCode).toBe(200);
+    expect(secondPage.json().projects).toHaveLength(1);
+    expect(secondPage.json().projects[0].id).not.toBe(firstPage.json().projects[0].id);
+  });
+
+  test('lists summaries across workspaces', async () => {
+    const firstWorkspaceId = crypto.randomUUID();
+    const secondWorkspaceId = crypto.randomUUID();
+    const firstProject = await createProject({
+      workspaceId: firstWorkspaceId,
+      name: 'GlobalAdminLookupAlpha',
+      sourceConnectionId: crypto.randomUUID(),
+      sourceExternalRepositoryId: 'gitea:global-admin-lookup-alpha',
+    });
+    const secondProject = await createProject({
+      workspaceId: secondWorkspaceId,
+      name: 'GlobalAdminLookupBeta',
+      sourceConnectionId: crypto.randomUUID(),
+      sourceExternalRepositoryId: 'gitea:global-admin-lookup-beta',
+    });
+
+    const res = await app.inject({
+      method: 'GET',
+      url: '/admin/projects?search=globaladminlookup&limit=100',
+      headers: {authorization: 'Bearer user'},
+    });
+
+    expect(res.statusCode).toBe(200);
+    expect(res.json().projects).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({id: firstProject.id, workspace_id: firstWorkspaceId}),
+        expect.objectContaining({id: secondProject.id, workspace_id: secondWorkspaceId}),
+      ]),
+    );
+  });
+
+  test('supports exact project ID lookup without exposing provider references', async () => {
+    const project = await createProject({
+      workspaceId,
+      name: 'Platform',
+      sourceConnectionId: crypto.randomUUID(),
+      sourceExternalRepositoryId: 'gitea:platform',
+    });
+
+    const res = await app.inject({
+      method: 'GET',
+      url: `/admin/projects?project_id=${project.id}`,
+      headers: {authorization: 'Bearer user'},
+    });
+
+    expect(res.statusCode).toBe(200);
+    expect(res.json().projects).toHaveLength(1);
+    expect(res.json().projects[0]).toMatchObject({
+      id: project.id,
+      name: 'Platform',
+      status: 'active',
+      workspace_id: workspaceId,
+    });
+    expect(res.json().projects[0]).not.toHaveProperty('source');
+  });
 });

package/src/presentation/subscribers/on-source-commit-pushed.test.ts

@@ -1,3 +1,4 @@
+import type {AuthInterModuleClient} from '@shipfox/api-auth-dto/inter-module';
 import {
   INTEGRATION_SOURCE_COMMIT_PUSHED,
   type IntegrationSourceCommitPushedEvent,
@@ -141,7 +142,10 @@ describe('onSourceCommitPushed', () => {
   // The source/event filter is the subscription itself, so this module should
   // only receive the typed source-control event.
   it('registers the projects module on INTEGRATION_SOURCE_COMMIT_PUSHED', () => {
-    const module = createProjectsModule({integrations: {} as IntegrationsModuleClient});
+    const module = createProjectsModule({
+      integrations: {} as IntegrationsModuleClient,
+      auth: {} as AuthInterModuleClient,
+    });
 
     const events = module.subscribers?.map((subscriber) => subscriber.event);