Public catalog API: templates, methods, and core values #54

2026-05-22T21:28:10Z

an.di commented

2026-05-22 21:28:10 +00:00

Overview

Exposes curated rule templates and built-in governance methods (communication, membership, decision-making, conflict management, and core values) through public, machine-readable HTTP APIs. External clients and integrations can discover the full catalog without importing messages/en/create/customRule/*.json or duplicating slug→copy maps.

Builds on existing facet ranking (GET /api/templates?facet.*, GET /api/create-flow/methods scores). The in-app wizard can keep using useMessages(); these routes are the stable contract for out-of-app consumers (English v1).

Changes

GET /api/templates/[slug] — single seeded template plus { section, slug } composition from templateMethodsFromBody; 404 when unknown; Cache-Control: public, max-age=3600
GET /api/create-flow/methods (extended) — full deck with label, description, sections for method sections; core values via section=coreValues (alias values); 1-based ids ("1", "2", …); optional matches when facet.* is present; full deck returned (ranking preserved, zero-score methods stay in list)
lib/server/governanceCatalog.ts — assembles DTOs from messages JSON (server-only)
getRuleTemplateBySlug in lib/server/ruleTemplates.ts
CATALOG_SECTION_IDS in lib/create/customRuleFacets.ts; catalogSectionIdSchema in methodFacetsSchemas.ts
fetchTemplateDetailBySlug / updated fetchTemplateBySlug in lib/create/fetchTemplates.ts (detail endpoint instead of full-list scan)
Tests: governanceCatalog.test.ts, templatesBySlugRoute.test.ts, extended createFlowMethodsRoute.test.ts and methodFacets.test.ts
Docs: CONTRIBUTING.md API table, template-recommendation-matrix.md §9 (de-ticketed), backend-linear-tickets.md Ticket 22 / CR-115 entry

Screenshots

N/A — API and documentation only.

How to Test

Setup: docker compose up -d postgres, .env with DATABASE_URL, npx prisma migrate dev, npx prisma db seed, npm run dev

Typecheck and unit tests:

npx tsc --noEmit
npx vitest run tests/unit/governanceCatalog.test.ts tests/unit/templatesBySlugRoute.test.ts tests/unit/createFlowMethodsRoute.test.ts tests/unit/methodFacets.test.ts

Template list and detail:

curl -s http://localhost:3000/api/templates | jq '.templates[0].slug'
curl -s http://localhost:3000/api/templates/consensus | jq '{slug: .template.slug, methods: .methods}'
curl -s http://localhost:3000/api/templates/unknown-slug -w '\n%{http_code}\n'  # expect 404

Methods catalog (full copy):

curl -s 'http://localhost:3000/api/create-flow/methods?section=communication' | jq '.methods[0] | {slug, label, description}'
curl -s 'http://localhost:3000/api/create-flow/methods?section=communication&facet.orgType=workersCoop&facet.size=sixToTwelve' | jq '[.methods[0:3][] | {slug, score: .matches.score}]'

Core values:

curl -s 'http://localhost:3000/api/create-flow/methods?section=coreValues' | jq '.methods[0:2]'
curl -s 'http://localhost:3000/api/create-flow/methods?section=values' | jq '.section'  # expect "coreValues"

Regression: confirm create-flow wizard method decks still reorder when community facets are selected (scores from API; copy still from messages)
Production build (optional): npx next build

## Overview Exposes curated rule templates and built-in governance methods (communication, membership, decision-making, conflict management, and core values) through public, machine-readable HTTP APIs. External clients and integrations can discover the full catalog without importing `messages/en/create/customRule/*.json` or duplicating slug→copy maps. Builds on existing facet ranking (`GET /api/templates?facet.*`, `GET /api/create-flow/methods` scores). The in-app wizard can keep using `useMessages()`; these routes are the stable contract for out-of-app consumers (English v1). ## Changes - **`GET /api/templates/[slug]`** — single seeded template plus `{ section, slug }` composition from `templateMethodsFromBody`; 404 when unknown; `Cache-Control: public, max-age=3600` - **`GET /api/create-flow/methods` (extended)** — full deck with `label`, `description`, `sections` for method sections; core values via `section=coreValues` (alias `values`); 1-based ids (`"1"`, `"2"`, …); optional `matches` when `facet.*` is present; full deck returned (ranking preserved, zero-score methods stay in list) - **`lib/server/governanceCatalog.ts`** — assembles DTOs from messages JSON (server-only) - **`getRuleTemplateBySlug`** in `lib/server/ruleTemplates.ts` - **`CATALOG_SECTION_IDS`** in `lib/create/customRuleFacets.ts`; `catalogSectionIdSchema` in `methodFacetsSchemas.ts` - **`fetchTemplateDetailBySlug`** / updated **`fetchTemplateBySlug`** in `lib/create/fetchTemplates.ts` (detail endpoint instead of full-list scan) - **Tests:** `governanceCatalog.test.ts`, `templatesBySlugRoute.test.ts`, extended `createFlowMethodsRoute.test.ts` and `methodFacets.test.ts` - **Docs:** `CONTRIBUTING.md` API table, `template-recommendation-matrix.md` §9 (de-ticketed), `backend-linear-tickets.md` Ticket 22 / CR-115 entry ## Screenshots N/A — API and documentation only. ## How to Test 1. **Setup:** `docker compose up -d postgres`, `.env` with `DATABASE_URL`, `npx prisma migrate dev`, `npx prisma db seed`, `npm run dev` 2. **Typecheck and unit tests:** ```bash npx tsc --noEmit npx vitest run tests/unit/governanceCatalog.test.ts tests/unit/templatesBySlugRoute.test.ts tests/unit/createFlowMethodsRoute.test.ts tests/unit/methodFacets.test.ts ``` 3. **Template list and detail:** ```bash curl -s http://localhost:3000/api/templates | jq '.templates[0].slug' curl -s http://localhost:3000/api/templates/consensus | jq '{slug: .template.slug, methods: .methods}' curl -s http://localhost:3000/api/templates/unknown-slug -w '\n%{http_code}\n' # expect 404 ``` 4. **Methods catalog (full copy):** ```bash curl -s 'http://localhost:3000/api/create-flow/methods?section=communication' | jq '.methods[0] | {slug, label, description}' curl -s 'http://localhost:3000/api/create-flow/methods?section=communication&facet.orgType=workersCoop&facet.size=sixToTwelve' | jq '[.methods[0:3][] | {slug, score: .matches.score}]' ``` 5. **Core values:** ```bash curl -s 'http://localhost:3000/api/create-flow/methods?section=coreValues' | jq '.methods[0:2]' curl -s 'http://localhost:3000/api/create-flow/methods?section=values' | jq '.section' # expect "coreValues" ``` 6. **Regression:** confirm create-flow wizard method decks still reorder when community facets are selected (scores from API; copy still from messages) 7. **Production build (optional):** `npx next build`

an.di self-assigned this 2026-05-22 21:28:10 +00:00

an.di added 1 commit 2026-05-22 21:28:11 +00:00

Add public API for methods and values 9e11063a11

an.di merged commit c663e051da into main

2026-05-22 21:28:37 +00:00

an.di deleted branch adilallo/PublicAPI

2026-05-22 21:28:38 +00:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: CommunityRule/community-rule#54