From d142f47464830cc97006bbdd1569c0f96f721575 Mon Sep 17 00:00:00 2001
From: Jake Bromberg <jake@funlandresearch.com>
Date: Sat, 14 Feb 2026 23:15:11 -0800
Subject: [PATCH] feat: add labels table and normalize label data

Add normalized label support to Backend-Service:

Schema:
- Add labels table (id, label_name, parent_label_id)
- Add label_id FK to library and flowsheet tables
- Add label_id to library_artist_view and rotation_library_view

Service layer:
- Add labels service with CRUD + search + upsert by name
- Add labels controller and routes (GET/POST /labels)
- Update library controller to resolve label strings to label_id
- Update library service to return label_id in queries
- Update flowsheet service to propagate label_id through entries
- Add label_id to V2 flowsheet track entries

Tests:
- Add labels service unit tests (8 tests)
- Add flowsheet label_id propagation test
- Update database mock with label support
---
 apps/backend/app.ts                           |   3 +
 .../controllers/flowsheet.controller.ts       |   3 +
 apps/backend/controllers/labels.controller.ts |  79 ++++++++++++
 .../backend/controllers/library.controller.ts |  10 ++
 apps/backend/routes/labels.route.ts           |  29 +++++
 apps/backend/services/flowsheet.service.ts    |   5 +
 apps/backend/services/labels.service.ts       |  59 +++++++++
 apps/backend/services/library.service.ts      |   3 +
 shared/database/src/schema.ts                 |  13 ++
 shared/database/src/types/flowsheet.types.ts  |   1 +
 tests/mocks/database.mock.ts                  |  14 +++
 tests/unit/services/flowsheet.service.test.ts |  14 +++
 tests/unit/services/labels.service.test.ts    | 116 ++++++++++++++++++
 13 files changed, 349 insertions(+)
 create mode 100644 apps/backend/controllers/labels.controller.ts
 create mode 100644 apps/backend/routes/labels.route.ts
 create mode 100644 apps/backend/services/labels.service.ts
 create mode 100644 tests/unit/services/labels.service.test.ts

diff --git a/apps/backend/app.ts b/apps/backend/app.ts
index b6b32c7d..38430d0a 100644
--- a/apps/backend/app.ts
+++ b/apps/backend/app.ts
@@ -6,6 +6,7 @@ import swaggerContent from './app.yaml';
 import { dj_route } from './routes/djs.route.js';
 import { flowsheet_route } from './routes/flowsheet.route.js';
 import { flowsheet_v2_route } from './routes/flowsheet.v2.route.js';
+import { labels_route } from './routes/labels.route.js';
 import { library_route } from './routes/library.route.js';
 import { schedule_route } from './routes/schedule.route.js';
 import { events_route } from './routes/events.route.js';
@@ -36,6 +37,8 @@ const swaggerDoc = parse_yaml(swaggerContent);
 app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDoc));
 
 // Business logic routes
+app.use('/labels', labels_route);
+
 app.use('/library', library_route);
 
 app.use('/flowsheet', flowsheet_route);
diff --git a/apps/backend/controllers/flowsheet.controller.ts b/apps/backend/controllers/flowsheet.controller.ts
index 6a5adc66..09d177ee 100644
--- a/apps/backend/controllers/flowsheet.controller.ts
+++ b/apps/backend/controllers/flowsheet.controller.ts
@@ -28,6 +28,7 @@ export interface IFSEntryMetadata {
 }
 
 export interface IFSEntry extends FSEntry {
+  label_id: number | null;
   rotation_play_freq: string | null;
   metadata: IFSEntryMetadata;
 }
@@ -125,6 +126,7 @@ export type FSEntryRequestBody = {
   album_id?: number;
   rotation_id?: number;
   record_label: string;
+  label_id?: number;
   request_flag?: boolean;
   message?: string;
 };
@@ -261,6 +263,7 @@ export type UpdateRequestBody = {
   album_title?: string;
   track_title?: string;
   record_label?: string;
+  label_id?: number;
   request_flag?: boolean;
   message?: string;
 };
diff --git a/apps/backend/controllers/labels.controller.ts b/apps/backend/controllers/labels.controller.ts
new file mode 100644
index 00000000..65dc493f
--- /dev/null
+++ b/apps/backend/controllers/labels.controller.ts
@@ -0,0 +1,79 @@
+import { Request, RequestHandler } from 'express';
+import * as labelsService from '../services/labels.service.js';
+
+type CreateLabelRequest = {
+  label_name: string;
+  parent_label_id?: number;
+};
+
+export const getLabels: RequestHandler = async (req, res, next) => {
+  try {
+    const labels = await labelsService.getAllLabels();
+    res.status(200).json(labels);
+  } catch (e) {
+    console.error('Error retrieving labels');
+    console.error(e);
+    next(e);
+  }
+};
+
+export const getLabel: RequestHandler<object, unknown, unknown, { id: string }> = async (req, res, next) => {
+  const id = parseInt(req.query.id);
+  if (isNaN(id)) {
+    res.status(400).json({ message: 'Missing or invalid label id' });
+  } else {
+    try {
+      const label = await labelsService.getLabelById(id);
+      if (label) {
+        res.status(200).json(label);
+      } else {
+        res.status(404).json({ message: 'Label not found' });
+      }
+    } catch (e) {
+      console.error('Error retrieving label');
+      console.error(e);
+      next(e);
+    }
+  }
+};
+
+export const createLabel: RequestHandler = async (
+  req: Request<object, object, CreateLabelRequest>,
+  res,
+  next
+) => {
+  const { body } = req;
+  if (!body.label_name) {
+    res.status(400).json({ message: 'Missing required parameter: label_name' });
+  } else {
+    try {
+      const label = await labelsService.createLabel(body.label_name, body.parent_label_id);
+      res.status(200).json(label);
+    } catch (e) {
+      console.error('Error creating label');
+      console.error(e);
+      next(e);
+    }
+  }
+};
+
+export const searchLabelsEndpoint: RequestHandler<object, unknown, unknown, { q: string; limit?: string }> = async (
+  req,
+  res,
+  next
+) => {
+  const query = req.query.q;
+  if (!query) {
+    res.status(400).json({ message: 'Missing required query parameter: q' });
+  } else {
+    try {
+      const limit = req.query.limit ? parseInt(req.query.limit) : undefined;
+      const labels = await labelsService.searchLabels(query, limit);
+      res.status(200).json(labels);
+    } catch (e) {
+      console.error('Error searching labels');
+      console.error(e);
+      next(e);
+    }
+  }
+};
diff --git a/apps/backend/controllers/library.controller.ts b/apps/backend/controllers/library.controller.ts
index 587628b5..801ec3d2 100644
--- a/apps/backend/controllers/library.controller.ts
+++ b/apps/backend/controllers/library.controller.ts
@@ -10,6 +10,7 @@ import {
   RotationRelease,
 } from '@wxyc/database';
 import * as libraryService from '../services/library.service.js';
+import * as labelsService from '../services/labels.service.js';
 
 type NewAlbumRequest = {
   album_title: string;
@@ -17,6 +18,7 @@ type NewAlbumRequest = {
   artist_id?: number;
   alternate_artist_name?: string;
   label: string;
+  label_id?: number;
   genre_id: number;
   format_id: number;
   disc_quantity?: number;
@@ -55,12 +57,20 @@ export const addAlbum: RequestHandler = async (req: Request<object, object, NewA
       );
     } else {
       try {
+        // Resolve label string to label_id via upsert
+        let label_id = body.label_id;
+        if (label_id === undefined && body.label) {
+          const resolvedLabel = await labelsService.createLabel(body.label);
+          label_id = resolvedLabel.id;
+        }
+
         const new_album: NewAlbum = {
           artist_id: artist_id,
           genre_id: body.genre_id,
           format_id: body.format_id,
           album_title: body.album_title,
           label: body.label,
+          label_id: label_id,
           code_number: await libraryService.generateAlbumCodeNumber(artist_id),
           alternate_artist_name: body.alternate_artist_name,
           disc_quantity: body.disc_quantity,
diff --git a/apps/backend/routes/labels.route.ts b/apps/backend/routes/labels.route.ts
new file mode 100644
index 00000000..11a2d64a
--- /dev/null
+++ b/apps/backend/routes/labels.route.ts
@@ -0,0 +1,29 @@
+import { requirePermissions } from "@wxyc/authentication";
+import { Router } from "express";
+import * as labelsController from "../controllers/labels.controller.js";
+
+export const labels_route = Router();
+
+labels_route.get(
+  "/",
+  requirePermissions({ catalog: ["read"] }),
+  labelsController.getLabels
+);
+
+labels_route.get(
+  "/info",
+  requirePermissions({ catalog: ["read"] }),
+  labelsController.getLabel
+);
+
+labels_route.get(
+  "/search",
+  requirePermissions({ catalog: ["read"] }),
+  labelsController.searchLabelsEndpoint
+);
+
+labels_route.post(
+  "/",
+  requirePermissions({ catalog: ["write"] }),
+  labelsController.createLabel
+);
diff --git a/apps/backend/services/flowsheet.service.ts b/apps/backend/services/flowsheet.service.ts
index 6bae271c..71fa1bf7 100644
--- a/apps/backend/services/flowsheet.service.ts
+++ b/apps/backend/services/flowsheet.service.ts
@@ -50,6 +50,7 @@ const FSEntryFieldsRaw = {
   album_title: flowsheet.album_title,
   track_title: flowsheet.track_title,
   record_label: flowsheet.record_label,
+  label_id: flowsheet.label_id,
   rotation_id: flowsheet.rotation_id,
   rotation_play_freq: rotation.play_freq,
   request_flag: flowsheet.request_flag,
@@ -80,6 +81,7 @@ type FSEntryRaw = {
   album_title: string | null;
   track_title: string | null;
   record_label: string | null;
+  label_id: number | null;
   rotation_id: number | null;
   rotation_play_freq: string | null;
   request_flag: boolean | null;
@@ -108,6 +110,7 @@ const transformToIFSEntry = (raw: FSEntryRaw): IFSEntry => ({
   album_title: raw.album_title,
   track_title: raw.track_title,
   record_label: raw.record_label,
+  label_id: raw.label_id,
   rotation_id: raw.rotation_id,
   rotation_play_freq: raw.rotation_play_freq,
   request_flag: raw.request_flag ?? false,
@@ -506,6 +509,7 @@ export const getAlbumFromDB = async (album_id: number) => {
       artist_name: artists.artist_name,
       album_title: library.album_title,
       record_label: library.label,
+      label_id: library.label_id,
     })
     .from(library)
     .innerJoin(artists, eq(artists.id, library.artist_id))
@@ -601,6 +605,7 @@ export const transformToV2 = (entry: IFSEntry): Record<string, unknown> => {
         album_title: entry.album_title,
         track_title: entry.track_title,
         record_label: entry.record_label,
+        label_id: entry.label_id,
         request_flag: entry.request_flag,
         rotation_play_freq: entry.rotation_play_freq,
         artwork_url: entry.metadata?.artwork_url ?? null,
diff --git a/apps/backend/services/labels.service.ts b/apps/backend/services/labels.service.ts
new file mode 100644
index 00000000..416ad027
--- /dev/null
+++ b/apps/backend/services/labels.service.ts
@@ -0,0 +1,59 @@
+import { eq, sql } from 'drizzle-orm';
+import { db, labels, Label } from '@wxyc/database';
+
+export const getAllLabels = async (): Promise<Label[]> => {
+  return await db.select().from(labels);
+};
+
+export const getLabelById = async (id: number): Promise<Label | undefined> => {
+  const result = await db
+    .select()
+    .from(labels)
+    .where(eq(labels.id, id))
+    .limit(1);
+  return result[0];
+};
+
+export const createLabel = async (
+  labelName: string,
+  parentLabelId?: number
+): Promise<Label> => {
+  const values: { label_name: string; parent_label_id?: number } = {
+    label_name: labelName,
+  };
+  if (parentLabelId !== undefined) {
+    values.parent_label_id = parentLabelId;
+  }
+
+  const result = await db
+    .insert(labels)
+    .values(values)
+    .onConflictDoNothing({ target: labels.label_name })
+    .returning();
+
+  // If conflict (label already exists), fetch the existing one
+  if (result.length === 0) {
+    const existing = await db
+      .select()
+      .from(labels)
+      .where(eq(labels.label_name, labelName))
+      .limit(1);
+    return existing[0];
+  }
+
+  return result[0];
+};
+
+export const searchLabels = async (
+  query: string,
+  limit = 10
+): Promise<Label[]> => {
+  const searchQuery = sql`
+    SELECT * FROM ${labels}
+    WHERE ${labels.label_name} ILIKE ${query + '%'}
+    ORDER BY ${labels.label_name}
+    LIMIT ${limit}
+  `;
+  const response = await db.execute(searchQuery);
+  return response.rows as Label[];
+};
diff --git a/apps/backend/services/library.service.ts b/apps/backend/services/library.service.ts
index b6c82fb9..98535337 100644
--- a/apps/backend/services/library.service.ts
+++ b/apps/backend/services/library.service.ts
@@ -39,6 +39,7 @@ export interface Rotation {
   artist_name: string;
   album_title: string;
   record_label: string | null;
+  label_id: number | null;
   genre_name: string;
   format_name: string;
   rotation_id: number;
@@ -59,6 +60,7 @@ export const getRotationFromDB = async (): Promise<Rotation[]> => {
       artist_name: artists.artist_name,
       album_title: library.album_title,
       record_label: library.label,
+      label_id: library.label_id,
       genre_name: genres.genre_name,
       format_name: format.format_name,
       rotation_id: rotation.id,
@@ -197,6 +199,7 @@ export const getAlbumFromDB = async (album_id: number) => {
       artist_name: artists.artist_name,
       album_title: library.album_title,
       record_label: library.label,
+      label_id: library.label_id,
       plays: library.plays,
       add_date: library.add_date,
       last_modified: library.last_modified,
diff --git a/shared/database/src/schema.ts b/shared/database/src/schema.ts
index f17f2b36..750c576e 100644
--- a/shared/database/src/schema.ts
+++ b/shared/database/src/schema.ts
@@ -244,6 +244,7 @@ export const library = wxyc_schema.table(
     alternate_artist_name: varchar('alternate_artist_name', { length: 128 }),
     album_title: varchar('album_title', { length: 128 }).notNull(),
     label: varchar('label', { length: 128 }),
+    label_id: integer('label_id').references(() => labels.id),
     code_number: smallint('code_number').notNull(),
     disc_quantity: smallint('disc_quantity').default(1).notNull(),
     plays: integer('plays').default(0).notNull(),
@@ -304,6 +305,7 @@ export const flowsheet = wxyc_schema.table('flowsheet', {
   album_title: varchar('album_title', { length: 128 }),
   artist_name: varchar('artist_name', { length: 128 }),
   record_label: varchar('record_label', { length: 128 }),
+  label_id: integer('label_id').references(() => labels.id),
   play_order: serial('play_order').notNull(),
   request_flag: boolean('request_flag').default(false).notNull(),
   message: varchar('message', { length: 250 }),
@@ -321,6 +323,14 @@ export const genres = wxyc_schema.table('genres', {
   last_modified: timestamp('last_modified').defaultNow().notNull(),
 });
 
+export type NewLabel = InferInsertModel<typeof labels>;
+export type Label = InferSelectModel<typeof labels>;
+export const labels = wxyc_schema.table('labels', {
+  id: serial('id').primaryKey(),
+  label_name: varchar('label_name', { length: 128 }).notNull().unique(),
+  parent_label_id: integer('parent_label_id'),
+});
+
 export type NewReview = InferInsertModel<typeof reviews>;
 export type Review = InferSelectModel<typeof reviews>;
 export const reviews = wxyc_schema.table('reviews', {
@@ -422,6 +432,7 @@ export type LibraryArtistViewEntry = {
   play_freq: string | null;
   add_date: Date;
   label: string | null;
+  label_id: number | null;
 };
 export const library_artist_view = wxyc_schema.view('library_artist_view').as((qb) => {
   return qb
@@ -437,6 +448,7 @@ export const library_artist_view = wxyc_schema.view('library_artist_view').as((q
       play_freq: rotation.play_freq,
       add_date: library.add_date,
       label: library.label,
+      label_id: library.label_id,
     })
     .from(library)
     .innerJoin(artists, eq(artists.id, library.artist_id))
@@ -454,6 +466,7 @@ export const rotation_library_view = wxyc_schema.view('rotation_library_view').a
       library_id: library.id,
       rotation_id: rotation.id,
       label: library.label,
+      label_id: library.label_id,
       play_freq: rotation.play_freq,
       album_title: library.album_title,
       artist_name: artists.artist_name,
diff --git a/shared/database/src/types/flowsheet.types.ts b/shared/database/src/types/flowsheet.types.ts
index 7a8cf263..b9e16669 100644
--- a/shared/database/src/types/flowsheet.types.ts
+++ b/shared/database/src/types/flowsheet.types.ts
@@ -39,6 +39,7 @@ export interface TrackEntryV2 extends BaseEntry {
   album_title: string | null;
   track_title: string | null;
   record_label: string | null;
+  label_id: number | null;
   request_flag: boolean;
   rotation_play_freq: string | null;
   // Album metadata from cache
diff --git a/tests/mocks/database.mock.ts b/tests/mocks/database.mock.ts
index 64a7e216..4d5ec9df 100644
--- a/tests/mocks/database.mock.ts
+++ b/tests/mocks/database.mock.ts
@@ -33,6 +33,9 @@ export function createMockQueryChain(resolvedValue: unknown = []): MockQueryChai
     'update',
     'set',
     'delete',
+    'onConflictDoNothing',
+    'onConflictDoUpdate',
+    'offset',
   ];
 
   chainMethods.forEach((method) => {
@@ -65,6 +68,7 @@ export const anonymous_devices = {};
 export const user_activity = {};
 export const album_metadata = {};
 export const artist_metadata = {};
+export const labels = {};
 export const library = {};
 export const artists = {};
 export const genres = {};
@@ -80,6 +84,7 @@ export const flowsheet = {
   album_title: 'album_title',
   artist_name: 'artist_name',
   record_label: 'record_label',
+  label_id: 'label_id',
   rotation_id: 'rotation_id',
   play_order: 'play_order',
   request_flag: 'request_flag',
@@ -111,6 +116,14 @@ export type ArtistMetadata = Record<string, unknown>;
 export type NewAlbumMetadata = Record<string, unknown>;
 export type NewArtistMetadata = Record<string, unknown>;
 
+export type Label = {
+  id: number;
+  label_name: string;
+  parent_label_id: number | null;
+};
+
+export type NewLabel = Partial<Label>;
+
 export type FSEntry = {
   id: number;
   show_id: number | null;
@@ -121,6 +134,7 @@ export type FSEntry = {
   album_title: string | null;
   artist_name: string | null;
   record_label: string | null;
+  label_id: number | null;
   play_order: number;
   request_flag: boolean;
   message: string | null;
diff --git a/tests/unit/services/flowsheet.service.test.ts b/tests/unit/services/flowsheet.service.test.ts
index 7812ea6b..5b84d54a 100644
--- a/tests/unit/services/flowsheet.service.test.ts
+++ b/tests/unit/services/flowsheet.service.test.ts
@@ -57,6 +57,7 @@ const createBaseEntry = (overrides: Partial<IFSEntry & IFSEntryMetadata> = {}):
     album_title: null,
     artist_name: null,
     record_label: null,
+    label_id: null,
     play_order: 1,
     request_flag: false,
     message: null,
@@ -100,6 +101,19 @@ describe('flowsheet.service', () => {
         expect(result.spotify_url).toBe('https://open.spotify.com/track/123');
       });
 
+      it('includes label_id in track entries', () => {
+        const entry = createBaseEntry({
+          entry_type: 'track',
+          artist_name: 'Merge Records Artist',
+          label_id: 42,
+          record_label: 'Merge Records',
+        });
+
+        const result = transformToV2(entry);
+
+        expect(result.label_id).toBe(42);
+      });
+
       it('excludes message field from track entries', () => {
         const entry = createBaseEntry({
           entry_type: 'track',
diff --git a/tests/unit/services/labels.service.test.ts b/tests/unit/services/labels.service.test.ts
new file mode 100644
index 00000000..57ea4ca1
--- /dev/null
+++ b/tests/unit/services/labels.service.test.ts
@@ -0,0 +1,116 @@
+import { db, createMockQueryChain, labels } from '../../mocks/database.mock';
+
+// Reset mocks before each test
+beforeEach(() => {
+  jest.clearAllMocks();
+});
+
+// Import after mocks are set up (module resolution uses moduleNameMapper)
+import {
+  getAllLabels,
+  getLabelById,
+  createLabel,
+  searchLabels,
+} from '../../../apps/backend/services/labels.service';
+
+describe('labels.service', () => {
+  describe('getAllLabels', () => {
+    it('returns all labels', async () => {
+      const mockLabels = [
+        { id: 1, label_name: 'Merge Records', parent_label_id: null },
+        { id: 2, label_name: 'Sub Pop', parent_label_id: null },
+      ];
+      const chain = createMockQueryChain(mockLabels);
+      // select().from() chain resolves via the last chainable method
+      // For select queries without returning(), the chain itself resolves
+      (db.select as jest.Mock).mockReturnValue(chain);
+      chain.from = jest.fn().mockResolvedValue(mockLabels);
+
+      const result = await getAllLabels();
+
+      expect(result).toEqual(mockLabels);
+      expect(db.select).toHaveBeenCalled();
+    });
+  });
+
+  describe('getLabelById', () => {
+    it('returns a label by id', async () => {
+      const mockLabel = { id: 1, label_name: 'Merge Records', parent_label_id: null };
+      const chain = createMockQueryChain([mockLabel]);
+      (db.select as jest.Mock).mockReturnValue(chain);
+      chain.limit = jest.fn().mockResolvedValue([mockLabel]);
+
+      const result = await getLabelById(1);
+
+      expect(result).toEqual(mockLabel);
+    });
+
+    it('returns undefined when label not found', async () => {
+      const chain = createMockQueryChain([]);
+      (db.select as jest.Mock).mockReturnValue(chain);
+      chain.limit = jest.fn().mockResolvedValue([]);
+
+      const result = await getLabelById(999);
+
+      expect(result).toBeUndefined();
+    });
+  });
+
+  describe('createLabel', () => {
+    it('inserts and returns a new label', async () => {
+      const mockLabel = { id: 1, label_name: 'Merge Records', parent_label_id: null };
+      const chain = createMockQueryChain([mockLabel]);
+      (db.insert as jest.Mock).mockReturnValue(chain);
+
+      const result = await createLabel('Merge Records');
+
+      expect(result).toEqual(mockLabel);
+      expect(db.insert).toHaveBeenCalled();
+    });
+
+    it('returns existing label on duplicate name (upsert)', async () => {
+      const mockLabel = { id: 1, label_name: 'Merge Records', parent_label_id: null };
+      const chain = createMockQueryChain([mockLabel]);
+      (db.insert as jest.Mock).mockReturnValue(chain);
+      // onConflictDoNothing returns the chain, then we select
+      chain.onConflictDoNothing = jest.fn().mockReturnValue(chain);
+
+      const result = await createLabel('Merge Records');
+
+      expect(result).toEqual(mockLabel);
+    });
+
+    it('sets parent_label_id when provided', async () => {
+      const mockLabel = { id: 2, label_name: 'Domino USA', parent_label_id: 1 };
+      const chain = createMockQueryChain([mockLabel]);
+      (db.insert as jest.Mock).mockReturnValue(chain);
+
+      const result = await createLabel('Domino USA', 1);
+
+      expect(result).toEqual(mockLabel);
+      expect(result.parent_label_id).toBe(1);
+    });
+  });
+
+  describe('searchLabels', () => {
+    it('filters labels by name prefix', async () => {
+      const mockLabels = [
+        { id: 1, label_name: 'Merge Records', parent_label_id: null },
+      ];
+      (db.execute as jest.Mock).mockResolvedValue({ rows: mockLabels });
+
+      const result = await searchLabels('Merge');
+
+      expect(result).toEqual(mockLabels);
+      expect(db.execute).toHaveBeenCalled();
+    });
+
+    it('returns empty array when no matches', async () => {
+      (db.execute as jest.Mock).mockResolvedValue({ rows: [] });
+
+      const result = await searchLabels('Nonexistent');
+
+      expect(result).toEqual([]);
+    });
+  });
+});