[HDX-2300] introduce Shared Filters for team-wide filter visibility and discoverability

.changeset/serious-chicken-hammer.md

@@ -0,0 +1,7 @@
+---
+"@hyperdx/common-utils": minor
+"@hyperdx/api": minor
+"@hyperdx/app": minor
+---
+
+Introduces Shared Filters, enabling teams to pin and surface common filters across all members.

packages/api/src/api-app.ts

@@ -12,6 +12,7 @@ import routers from './routers/api';
 import clickhouseProxyRouter from './routers/api/clickhouseProxy';
 import connectionsRouter from './routers/api/connections';
 import favoritesRouter from './routers/api/favorites';
+import pinnedFiltersRouter from './routers/api/pinnedFilters';
 import savedSearchRouter from './routers/api/savedSearch';
 import sourcesRouter from './routers/api/sources';
 import externalRoutersV2 from './routers/external-api/v2';
@@ -101,6 +102,7 @@ app.use('/connections', isUserAuthenticated, connectionsRouter);
 app.use('/sources', isUserAuthenticated, sourcesRouter);
 app.use('/saved-search', isUserAuthenticated, savedSearchRouter);
 app.use('/favorites', isUserAuthenticated, favoritesRouter);
+app.use('/pinned-filters', isUserAuthenticated, pinnedFiltersRouter);
 app.use('/clickhouse-proxy', isUserAuthenticated, clickhouseProxyRouter);
 // ---------------------------------------------------------------------
 

packages/api/src/controllers/pinnedFilter.ts

@@ -0,0 +1,44 @@
+import type { PinnedFiltersValue } from '@hyperdx/common-utils/dist/types';
+import mongoose from 'mongoose';
+
+import type { ObjectId } from '@/models';
+import PinnedFilterModel from '@/models/pinnedFilter';
+
+/**
+ * Get team-level pinned filters for a team+source combination.
+ */
+export async function getPinnedFilters(
+  teamId: string | ObjectId,
+  sourceId: string | ObjectId,
+) {
+  return PinnedFilterModel.findOne({
+    team: new mongoose.Types.ObjectId(teamId),
+    source: new mongoose.Types.ObjectId(sourceId),
+    user: null,
+  });
+}
+
+/**
+ * Upsert team-level pinned filters for a team+source.
+ */
+export async function updatePinnedFilters(
+  teamId: string | ObjectId,
+  sourceId: string | ObjectId,
+  data: { fields: string[]; filters: PinnedFiltersValue },
+) {
+  const filter = {
+    team: new mongoose.Types.ObjectId(teamId),
+    source: new mongoose.Types.ObjectId(sourceId),
+    user: null,
+  };
+
+  return PinnedFilterModel.findOneAndUpdate(
+    filter,
+    {
+      ...filter,
+      fields: data.fields,
+      filters: data.filters,
+    },
+    { upsert: true, new: true },
+  );
+}

packages/api/src/models/pinnedFilter.ts

@@ -0,0 +1,56 @@
+import type { PinnedFiltersValue } from '@hyperdx/common-utils/dist/types';
+import mongoose, { Schema } from 'mongoose';
+
+import type { ObjectId } from '.';
+
+interface IPinnedFilter {
+  _id: ObjectId;
+  team: ObjectId;
+  source: ObjectId;
+  user: ObjectId | null; // null = team-level, non-null = personal
+  fields: string[];
+  filters: PinnedFiltersValue;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+const PinnedFilterSchema = new Schema<IPinnedFilter>(
+  {
+    team: {
+      type: mongoose.Schema.Types.ObjectId,
+      required: true,
+      ref: 'Team',
+    },
+    source: {
+      type: mongoose.Schema.Types.ObjectId,
+      required: true,
+      ref: 'Source',
+    },
+    user: {
+      type: mongoose.Schema.Types.ObjectId,
+      default: null,
+      ref: 'User',
+    },
+    fields: {
+      type: [String],
+      default: [],
+    },
+    filters: {
+      type: Schema.Types.Mixed,
+      default: {},
+    },
+  },
+  {
+    timestamps: true,
+    toJSON: { getters: true },
+  },
+);
+
+// One document per team+source+user combination
+// user=null means team-level pins
+PinnedFilterSchema.index({ team: 1, source: 1, user: 1 }, { unique: true });
+
+export default mongoose.model<IPinnedFilter>(
+  'PinnedFilter',
+  PinnedFilterSchema,
+);

packages/api/src/routers/api/__tests__/pinnedFilters.test.ts

@@ -0,0 +1,214 @@
+import { SourceKind, TSource } from '@hyperdx/common-utils/dist/types';
+import { Types } from 'mongoose';
+
+import { getLoggedInAgent, getServer } from '@/fixtures';
+import { Source } from '@/models/source';
+
+const MOCK_SOURCE: Omit<Extract<TSource, { kind: 'log' }>, 'id'> = {
+  kind: SourceKind.Log,
+  name: 'Test Source',
+  connection: new Types.ObjectId().toString(),
+  from: { databaseName: 'test_db', tableName: 'test_table' },
+  timestampValueExpression: 'timestamp',
+  defaultTableSelectExpression: 'body',
+};
+
+describe('pinnedFilters router', () => {
+  const server = getServer();
+  let agent: Awaited<ReturnType<typeof getLoggedInAgent>>['agent'];
+  let team: Awaited<ReturnType<typeof getLoggedInAgent>>['team'];
+  let sourceId: string;
+
+  beforeAll(async () => {
+    await server.start();
+  });
+
+  beforeEach(async () => {
+    const result = await getLoggedInAgent(server);
+    agent = result.agent;
+    team = result.team;
+
+    // Create a real source owned by this team
+    const source = await Source.create({ ...MOCK_SOURCE, team: team._id });
+    sourceId = source._id.toString();
+  });
+
+  afterEach(async () => {
+    await server.clearDBs();
+  });
+
+  afterAll(async () => {
+    await server.stop();
+  });
+
+  describe('GET /pinned-filters', () => {
+    it('returns null when no pinned filters exist', async () => {
+      const res = await agent
+        .get(`/pinned-filters?source=${sourceId}`)
+        .expect(200);
+
+      expect(res.body.team).toBeNull();
+    });
+
+    it('rejects invalid source id', async () => {
+      await agent.get('/pinned-filters?source=not-an-objectid').expect(400);
+    });
+
+    it('rejects missing source param', async () => {
+      await agent.get('/pinned-filters').expect(400);
+    });
+
+    it('returns 404 for a source not owned by the team', async () => {
+      const foreignSourceId = new Types.ObjectId().toString();
+      await agent.get(`/pinned-filters?source=${foreignSourceId}`).expect(404);
+    });
+  });
+
+  describe('PUT /pinned-filters', () => {
+    it('can create pinned filters', async () => {
+      const res = await agent
+        .put('/pinned-filters')
+        .send({
+          source: sourceId,
+          fields: ['ServiceName', 'SeverityText'],
+          filters: { ServiceName: ['web', 'api'] },
+        })
+        .expect(200);
+
+      expect(res.body.fields).toEqual(['ServiceName', 'SeverityText']);
+      expect(res.body.filters).toEqual({ ServiceName: ['web', 'api'] });
+      expect(res.body.id).toBeDefined();
+    });
+
+    it('upserts on repeated PUT', async () => {
+      await agent
+        .put('/pinned-filters')
+        .send({
+          source: sourceId,
+          fields: ['ServiceName'],
+          filters: { ServiceName: ['web'] },
+        })
+        .expect(200);
+
+      const res = await agent
+        .put('/pinned-filters')
+        .send({
+          source: sourceId,
+          fields: ['ServiceName', 'SeverityText'],
+          filters: { ServiceName: ['web', 'api'], SeverityText: ['error'] },
+        })
+        .expect(200);
+
+      expect(res.body.fields).toEqual(['ServiceName', 'SeverityText']);
+      expect(res.body.filters).toEqual({
+        ServiceName: ['web', 'api'],
+        SeverityText: ['error'],
+      });
+    });
+
+    it('rejects invalid source id', async () => {
+      await agent
+        .put('/pinned-filters')
+        .send({ source: 'not-valid', fields: [], filters: {} })
+        .expect(400);
+    });
+
+    it('returns 404 for a source not owned by the team', async () => {
+      const foreignSourceId = new Types.ObjectId().toString();
+      await agent
+        .put('/pinned-filters')
+        .send({ source: foreignSourceId, fields: [], filters: {} })
+        .expect(404);
+    });
+  });
+
+  describe('GET + PUT round-trip', () => {
+    it('returns data after PUT', async () => {
+      await agent
+        .put('/pinned-filters')
+        .send({
+          source: sourceId,
+          fields: ['ServiceName'],
+          filters: { ServiceName: ['web'] },
+        })
+        .expect(200);
+
+      const res = await agent
+        .get(`/pinned-filters?source=${sourceId}`)
+        .expect(200);
+
+      expect(res.body.team).not.toBeNull();
+      expect(res.body.team.fields).toEqual(['ServiceName']);
+      expect(res.body.team.filters).toEqual({ ServiceName: ['web'] });
+    });
+
+    it('can reset by sending empty fields and filters', async () => {
+      await agent
+        .put('/pinned-filters')
+        .send({
+          source: sourceId,
+          fields: ['ServiceName'],
+          filters: { ServiceName: ['web'] },
+        })
+        .expect(200);
+
+      await agent
+        .put('/pinned-filters')
+        .send({ source: sourceId, fields: [], filters: {} })
+        .expect(200);
+
+      const res = await agent
+        .get(`/pinned-filters?source=${sourceId}`)
+        .expect(200);
+
+      expect(res.body.team).not.toBeNull();
+      expect(res.body.team.fields).toEqual([]);
+      expect(res.body.team.filters).toEqual({});
+    });
+  });
+
+  describe('source scoping', () => {
+    it('pins are scoped to their source', async () => {
+      const source2 = await Source.create({ ...MOCK_SOURCE, team: team._id });
+
+      await agent
+        .put('/pinned-filters')
+        .send({
+          source: sourceId,
+          fields: ['ServiceName'],
+          filters: { ServiceName: ['web'] },
+        })
+        .expect(200);
+
+      const res = await agent
+        .get(`/pinned-filters?source=${source2._id}`)
+        .expect(200);
+
+      expect(res.body.team).toBeNull();
+    });
+  });
+
+  // Note: cross-team isolation (Team B cannot read Team A's pins) is enforced
+  // by the MongoDB query filtering on teamId AND the source ownership check
+  // (getSource validates source.team === teamId). Multi-team integration tests
+  // are not possible in this single-team environment (register returns 409).
+
+  describe('filter values with booleans', () => {
+    it('supports boolean values in filters', async () => {
+      await agent
+        .put('/pinned-filters')
+        .send({
+          source: sourceId,
+          fields: ['isRootSpan'],
+          filters: { isRootSpan: [true, false] },
+        })
+        .expect(200);
+
+      const res = await agent
+        .get(`/pinned-filters?source=${sourceId}`)
+        .expect(200);
+
+      expect(res.body.team.filters).toEqual({ isRootSpan: [true, false] });
+    });
+  });
+});