feat: package model in the commons API - #151
Closed
jzongker wants to merge 1 commit into
Closed
Conversation
Adds the package-model columns to songs (confidence tier, first line, rights and form maps, sing time, score source, listen-gate record), seeds them from the content repo packages (masters/song.json, derivatives/*, work inheritance), and recomputes them in the song publish hook. GET /commons/songs rows gain confidence/sundayReady/featured/has* flags and the sundayReady/confidence/ language/q filters; the detail adds rights, rightsMatrix, ccliReport, attribution, form, publishedKeys, contributors and the new fileUrls roles. New GET /commons/songs/:id/page bundles song + rating + history + family + similar, and POST /commons/admin/songs/:id/listen records the listen gate. Tests: RightsHelper table, seed reader against a fixture package repo, package shaping, /page shape, listen-gate transitions, publish hook fields.
This was referenced Sep 8, 2026
Closed
4 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
2026-09-07_package_modeladdsconfidence, firstLine, tune, hasChords, rights, form, recommendedKey, recommendedKeyReason, publishedKeys, singTimeSeconds, scoreSource, listenedKeys, sundayReadyBy, sundayReadyAttosongs.tools/commons-seed/catalog.ts) now resolves each row's package dir (from its paths, or by id when every path points at a work), readsmasters/song.jsonfor rights/form/meter andderivatives/duration.jsonfor sing time, marksscoreSource: "abc"when ascore.musicxmlis served (own or inherited from the work, the wayabcUrlalready resolves), and copiesscore.musicxml, slides.json, chart.chordpro, chart.pdf, attribution.txt, duration.json, cover-thumb.webpflat intoassets/song/{id}/.tools/manual/commons-sync-catalog.ts(previously untracked) is committed with the new columns in its--updateset.GET /commons/songsrows addconfidence, sundayReady, featured, firstLine, tune, hasChords, hasScore, hasSlides, hasTiming, hasAccompaniment (false), recommendedKey, singTimeSeconds; query paramssundayReady=true,confidence=,language=,q=(title / first line / writer).rankordering and every existing key kept; reviewer-only fields still never leave.GET /commons/songs/:idaddsrights, rightsMatrix, ccliReport, attribution, form, publishedKeys, recommendedKeyReason, scoreSource, contributors, sundayReadyAt, sundayReadyBy, listenedKeysand thefileUrlsrolesscore, slides, chart, chartPdf, attribution, thumb, duration.fileRole()lives in@churchapps/helpers, so the new names are mapped inContentLibraryHelper.role()(the manifest hook uses it too);lyrics.chordprostill maps tochartand wins overchart.chordprowhen both are served.GET /commons/songs/:id/page→{ song, rating: { average, count, mine }, history, family, similar };mineonly with a user JWT. Similar: same language, not family, +2 meter, +2 scripture book, +1 per shared theme, top 6 with a one-sentencereason.helpers/RightsHelper.ts:matrixForLicense,composeMatrix,ccliReportper the contract table (mirrors the site'ssrc/rights.ts).sunday-readyunless lyrics or score files changed (then clears the listen record).song.json.statusis written from the asset status, never the literal.POST /commons/admin/songs/:id/listen { keys }records the listen gate;sunday-readywhen the keys coverpublishedKeysand the package serves score + chords + slides;{ keys: [] }clears. Reviewer check lives in one place:helpers/ReviewAccess.tscanReview(au).src/modules/commons/README.mddocuments the model, the/pageendpoint and the query params.Test plan
yarn jest src/modules/commons— 20 suites, 190 tests pass (new:RightsHelper,SeedCatalogagainst__tests__/fixtures/package-repo,SongPackageHelper,SongPage,ListenGate,SongPublishHook;ContentLibraryHelpergained fileUrls-role and song.json-status cases)yarn tsc --noEmitclean;yarn eslint --fix src/modules/commonscleanyarn reset-commonsagainst a local MySQL to exercise the migration + seedCross-repo
Depends on / pairs with: WorshipCommons
feat/site-package-contract(consumer); B1Admin package-model job (consumer). The submission-types branch addssongs.contributors—contributorsreads[]until that column exists.Migration: required on staging/prod (
2026-09-07_package_model), thencommons-sync-catalog.ts --updateto fill the new columns for existing rows.Left out
/v1) — deliberately skipped; routes stay/commons/....recommendedKey/recommendedKeyReasonare stored and served but never computed (contract marks it optional; no MIDI melody-range fit here) —nulltoday.COMMONS_MUSIC_EDITORS) —canReview()is the single swap point for the branch that adds them.tuneis reserved and alwaysnull.