feat(prompts): add GET /v2/orgs/:spaceCatId/brands/:brandId/prompts/stats endpoint (#2528)

## Summary

Adds a new aggregate endpoint that returns prompt counts per brand for
the `project-elmo-ui` Prompts Management tab status bar.

- `GET /v2/orgs/:spaceCatId/brands/:brandId/prompts/stats`
- Returns `{ branded, unbranded, intents: { informational,
instructional, comparative, transactional, planning, delegation } }`
- Backed by the `rpc_brand_prompt_stats` PostgREST RPC in
`mysticat-data-service` - all classification logic stays in SQL, no
write-path changes or backfill required on the API side

## Design note

This replaces the originally-spec'd approach of storing a derived
`branded` column on `prompts` and reclassifying inside brand-mutation
transactions. The RPC computes counts at read time using the current
brand name + aliases, which removes the consistency model complexity
(transactional reclassify, 250K row-count gate, backfill script) at the
cost of slightly slower reads. Partial index on `(organization_id,
brand_id, status) WHERE status = 'active'` keeps the query fast.

Intent counts read 0 until the DRS to Postgres ingestion workstream
forwards `intent` on prompts upsert (separate, prerequisite workstream).

## Test plan

- [ ] Unit tests for `getPromptStats` (RPC happy path, error path,
missing intents hydration)
- [ ] Unit tests for `getPromptStatsByBrand` controller (auth, org not
found, brand not found, postgrest unavailable)
- [ ] Integration test in `test/it/postgres/`
- [ ] Manual smoke against staging: `curl
/v2/orgs/<orgId>/brands/<brandId>/prompts/stats` returns flat shape with
all 6 intent keys

Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: nsdere

src/controllers/brands.js

@@ -37,6 +37,7 @@ import {
   deletePromptById,
   bulkDeletePrompts,
   checkPromptsExist,
+  getPromptStats,
   resolveBrandUuid,
 } from '../support/prompts-storage.js';
 import {
@@ -657,6 +658,53 @@ function BrandsController(ctx, log, env) {
     }
   };
 
+  const getPromptStatsByBrand = async (context) => {
+    const { spaceCatId, brandId } = context.params || {};
+
+    try {
+      if (!hasText(spaceCatId)) {
+        return badRequest('Organization ID required');
+      }
+      if (!isValidUUID(spaceCatId)) {
+        return badRequest('Organization ID must be a valid UUID');
+      }
+      if (!hasText(brandId)) {
+        return badRequest('Brand ID required');
+      }
+
+      const organization = await getOrganizationOrNotFound(spaceCatId);
+      if (organization.status) {
+        return organization;
+      }
+      if (!await accessControlUtil.hasAccess(organization)) {
+        return forbidden('User does not have access to this organization');
+      }
+
+      const unavailable = requirePostgrestForV2Config(context);
+      if (unavailable) {
+        return unavailable;
+      }
+
+      const { postgrestClient } = context.dataAccess.services;
+
+      const brandUuid = await resolveBrandUuid(spaceCatId, brandId, postgrestClient);
+      if (!brandUuid) {
+        return notFound(`Brand not found: ${brandId}`);
+      }
+
+      const stats = await getPromptStats({
+        organizationId: spaceCatId,
+        brandUuid,
+        postgrestClient,
+      });
+
+      return ok(stats);
+    } catch (error) {
+      log.error('Error fetching prompt stats', { brandId, error });
+      return createErrorResponse(error);
+    }
+  };
+
   // ── Brand list (v2, reads from normalized tables) ──
 
   const getBrandForOrg = async (context) => {
@@ -1384,6 +1432,7 @@ function BrandsController(ctx, log, env) {
     deleteBrandForOrg,
     listPromptsByBrand,
     getPromptByBrandAndId,
+    getPromptStatsByBrand,
     createPromptsByBrand,
     updatePromptByBrandAndId,
     deletePromptByBrandAndId,

src/routes/index.js

@@ -213,6 +213,7 @@ export default function getRouteHandlers(
     'GET /v2/orgs/:spaceCatId/brands/:brandId/serenity/tags': serenityController.listTags,
     'GET /v2/orgs/:spaceCatId/brands/:brandId/serenity/models': serenityController.listModels,
     'GET /v2/orgs/:spaceCatId/brands/:brandId/prompts': brandsController.listPromptsByBrand,
+    'GET /v2/orgs/:spaceCatId/brands/:brandId/prompts/stats': brandsController.getPromptStatsByBrand,
     'POST /v2/orgs/:spaceCatId/brands/:brandId/prompts': brandsController.createPromptsByBrand,
     'GET /v2/orgs/:spaceCatId/brands/:brandId/prompts/:promptId': brandsController.getPromptByBrandAndId,
     'PATCH /v2/orgs/:spaceCatId/brands/:brandId/prompts/:promptId': brandsController.updatePromptByBrandAndId,

src/routes/required-capabilities.js

@@ -257,6 +257,7 @@ const routeRequiredCapabilities = {
   'PATCH /v2/orgs/:spaceCatId/brands/:brandId': 'organization:write',
   'DELETE /v2/orgs/:spaceCatId/brands/:brandId': 'organization:write',
   'GET /v2/orgs/:spaceCatId/brands/:brandId/prompts': 'organization:read',
+  'GET /v2/orgs/:spaceCatId/brands/:brandId/prompts/stats': 'organization:read',
   'GET /v2/orgs/:spaceCatId/brands/:brandId/prompts/:promptId': 'organization:read',
   'POST /v2/orgs/:spaceCatId/brands/:brandId/prompts': 'organization:write',
   'PATCH /v2/orgs/:spaceCatId/brands/:brandId/prompts/:promptId': 'organization:write',

src/support/prompts-storage.js

@@ -815,3 +815,36 @@ export async function checkPromptsExist({ brandUuid, prompts, postgrestClient })
 
   return data ?? [];
 }
+
+const INTENT_VALUES = ['informational', 'instructional', 'comparative', 'transactional', 'planning', 'delegation'];
+
+export async function getPromptStats({ organizationId, brandUuid, postgrestClient }) {
+  if (!postgrestClient?.rpc) {
+    throw new Error('PostgREST client is required');
+  }
+
+  const { data, error } = await postgrestClient.rpc('rpc_brand_prompt_stats', {
+    p_organization_id: organizationId,
+    p_brand_id: brandUuid,
+  });
+
+  if (error) {
+    throw new Error(`getPromptStats RPC failed: ${error.message}`);
+  }
+
+  const row = Array.isArray(data) && data.length > 0 ? data[0] : (data ?? {});
+  const intents = Object.fromEntries(INTENT_VALUES.map((k) => [k, 0]));
+  if (row.intents && typeof row.intents === 'object') {
+    for (const [k, v] of Object.entries(row.intents)) {
+      if (INTENT_VALUES.includes(k)) {
+        intents[k] = Number(v) || 0;
+      }
+    }
+  }
+
+  return {
+    branded: Number(row.branded) || 0,
+    unbranded: Number(row.unbranded) || 0,
+    intents,
+  };
+}

test/controllers/brands.test.js

@@ -2060,6 +2060,150 @@ describe('Brands Controller', () => {
     });
   });
 
+  describe('getPromptStatsByBrand', () => {
+    const BRAND_UUID = 'd1111111-1111-4111-b111-111111111111';
+    const STATS_RESPONSE = {
+      branded: 42,
+      unbranded: 1208,
+      intents: {
+        informational: 410,
+        instructional: 180,
+        comparative: 95,
+        transactional: 250,
+        planning: 60,
+        delegation: 15,
+      },
+    };
+
+    beforeEach(() => {
+      mockDataAccess.services.postgrestClient = {
+        from: sandbox.stub().callsFake((table) => ({
+          select: sandbox.stub().returnsThis(),
+          eq: sandbox.stub().returnsThis(),
+          maybeSingle: sandbox.stub().callsFake(() => {
+            if (table === 'brands') {
+              return Promise.resolve({ data: { id: BRAND_UUID }, error: null });
+            }
+            return Promise.resolve({ data: null, error: null });
+          }),
+        })),
+        rpc: sandbox.stub().resolves({ data: STATS_RESPONSE, error: null }),
+      };
+      brandsController = BrandsController(context, loggerStub, mockEnv);
+    });
+
+    it('returns 400 when spaceCatId is missing', async () => {
+      const response = await brandsController.getPromptStatsByBrand({
+        ...context,
+        params: { brandId: BRAND_UUID },
+        dataAccess: mockDataAccess,
+      });
+      expect(response.status).to.equal(400);
+    });
+
+    it('returns 400 when spaceCatId is not a valid UUID', async () => {
+      const response = await brandsController.getPromptStatsByBrand({
+        ...context,
+        params: { spaceCatId: 'not-a-uuid', brandId: BRAND_UUID },
+        dataAccess: mockDataAccess,
+      });
+      expect(response.status).to.equal(400);
+    });
+
+    it('returns 400 when brandId is missing', async () => {
+      const response = await brandsController.getPromptStatsByBrand({
+        ...context,
+        params: { spaceCatId: ORGANIZATION_ID },
+        dataAccess: mockDataAccess,
+      });
+      expect(response.status).to.equal(400);
+    });
+
+    it('returns 404 when organization is not found', async () => {
+      mockDataAccess.Organization.findById = sinon.stub().resolves(null);
+      const response = await brandsController.getPromptStatsByBrand({
+        ...context,
+        params: { spaceCatId: ORGANIZATION_ID, brandId: BRAND_UUID },
+        dataAccess: mockDataAccess,
+      });
+      expect(response.status).to.equal(404);
+    });
+
+    it('returns 403 when user lacks access to the organization', async () => {
+      const authContextUser = {
+        attributes: {
+          authInfo: new AuthInfo()
+            .withType('jwt')
+            .withScopes([{ name: 'user' }])
+            .withProfile({ is_admin: false })
+            .withAuthenticated(true),
+        },
+      };
+      const unauthorizedController = BrandsController({
+        dataAccess: mockDataAccess,
+        pathInfo: { headers: { 'x-product': 'llmo' } },
+        ...authContextUser,
+      }, loggerStub, mockEnv);
+      const response = await unauthorizedController.getPromptStatsByBrand({
+        params: { spaceCatId: ORGANIZATION_ID, brandId: BRAND_UUID },
+        dataAccess: mockDataAccess,
+      });
+      expect(response.status).to.equal(403);
+    });
+
+    it('returns 503 when postgrestClient is not available', async () => {
+      mockDataAccess.services.postgrestClient = null;
+      const response = await brandsController.getPromptStatsByBrand({
+        ...context,
+        params: { spaceCatId: ORGANIZATION_ID, brandId: BRAND_UUID },
+        dataAccess: mockDataAccess,
+      });
+      expect(response.status).to.equal(503);
+    });
+
+    it('returns 404 when brand is not found', async () => {
+      mockDataAccess.services.postgrestClient.from = sandbox.stub().callsFake(() => ({
+        select: sandbox.stub().returnsThis(),
+        eq: sandbox.stub().returnsThis(),
+        maybeSingle: sandbox.stub().resolves({ data: null, error: null }),
+      }));
+      const response = await brandsController.getPromptStatsByBrand({
+        ...context,
+        params: { spaceCatId: ORGANIZATION_ID, brandId: BRAND_UUID },
+        dataAccess: mockDataAccess,
+      });
+      expect(response.status).to.equal(404);
+    });
+
+    it('returns 200 with the flat stats shape on success', async () => {
+      const response = await brandsController.getPromptStatsByBrand({
+        ...context,
+        params: { spaceCatId: ORGANIZATION_ID, brandId: BRAND_UUID },
+        dataAccess: mockDataAccess,
+      });
+      expect(response.status).to.equal(200);
+      const body = await response.json();
+      expect(body).to.have.property('branded', 42);
+      expect(body).to.have.property('unbranded', 1208);
+      expect(body).to.have.property('intents').that.includes({ informational: 410, delegation: 15 });
+    });
+
+    it('returns 500 when storage throws and logs the error', async () => {
+      const dbError = new Error('RPC failure');
+      mockDataAccess.services.postgrestClient.rpc = sandbox.stub().rejects(dbError);
+      const response = await brandsController.getPromptStatsByBrand({
+        ...context,
+        params: { spaceCatId: ORGANIZATION_ID, brandId: BRAND_UUID },
+        dataAccess: mockDataAccess,
+      });
+      expect(response.status).to.equal(500);
+      expect(loggerStub.error).to.have.been.calledWith('Error fetching prompt stats', {
+        brandId: BRAND_UUID,
+        error: dbError,
+      });
+    });
+  });
+
   describe('listBrandsForOrg', () => {
     beforeEach(() => {
       mockDataAccess.services.postgrestClient = {

test/routes/index.test.js

@@ -740,6 +740,7 @@ describe('getRouteHandlers', () => {
       'PATCH /v2/orgs/:spaceCatId/brands/:brandId',
       'DELETE /v2/orgs/:spaceCatId/brands/:brandId',
       'GET /v2/orgs/:spaceCatId/brands/:brandId/prompts',
+      'GET /v2/orgs/:spaceCatId/brands/:brandId/prompts/stats',
       'POST /v2/orgs/:spaceCatId/brands/:brandId/prompts',
       'GET /v2/orgs/:spaceCatId/brands/:brandId/prompts/:promptId',
       'PATCH /v2/orgs/:spaceCatId/brands/:brandId/prompts/:promptId',