@withpica/mcp-sdk 1.3.0 → 1.7.0

package/CHANGELOG.md

@@ -0,0 +1,237 @@
+# Changelog
+
+All notable changes to `@withpica/mcp-sdk` will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+> **Rule of the road:** every version bump to this package MUST land with a
+> matching entry here in the same commit. See the project's "npm publish
+> discipline" memory entry for the enforcement rationale.
+
+## [Unreleased]
+
+## [1.7.0] - 2026-04-18
+
+### Fixed
+
+- **ADR-179 Phase 3 SDK gap: `EnrichmentResource.resolveRecording` method
+  added.** The type `ResolveRecordingResult` shipped with commit
+  `63d97dd28` but the method itself was missing — `mcp-server/` stdio
+  tool `pica_resolve_recording` called `this.pica.enrichment.resolveRecording(...)`
+  against a method that didn't exist, breaking sub-package typecheck and
+  runtime. Signature mirrors `resolveWork` / `resolvePerson`:
+  `resolveRecording(recordingId, { sources?, includeFuzzy? })`. Routes to
+  `POST /admin/recordings/{id}/resolve`.
+
+### Added
+
+- **ADR-174 Phase 2 item 7 follow-up: `ProjectsResource.attachWork`.** New
+  SDK method wrapping `POST /admin/projects/{id}/works` — closes the
+  `work_ids` gap on `pica_projects_create` / `_update` where the admin
+  route silently dropped the field. Signature:
+  `attachWork(projectId, { work_id, project_day?, notes? })`. Backs the
+  new `pica_projects_attach_works` batch MCP tool (loops one SDK call
+  per item) in `@withpica/mcp-server`.
+
+### Changed
+
+- **ADR-174 Phase 2 item 22: `PublishersResource.create` signature widened
+  to `Record<string, unknown>`.** Pre-slice the method was typed
+  `{ name: string; ipi?: string }` and returned 404 at runtime (the route
+  did not exist). With the new `POST /api/admin/publishers` route shipped
+  in the companion commit, the SDK now accepts the full audit-row-22
+  surface (name, ipi_number, legal_name, country, isni, publisher_type,
+  wikidata_id, parent_publisher_id, founded_date, headquarters). The
+  `ipi → ipi_number` rename is explicit at the route layer — callers
+  still passing `ipi` get a PHANTOM_FIELD error with a rename hint.
+
+### Added
+
+- **ADR-179 Phase 1: `EnrichmentResource.resolveWork(workId, options?)`.**
+  Outcome-shaped resolver that fans a work out across every eligible
+  enrichment source in one call. Wraps the new `POST /admin/works/{id}/resolve`
+  endpoint. Accepts an optional `sources` whitelist (`mlc` | `spotify` |
+  `youtube` | `musicbrainz` | `discogs`) and `includeFuzzy` flag.
+  Returns `ResolveWorkResult` with `applied[]` (Tier A writes),
+  `proposals[]` (Tier B review queue rows), `errors[]` (per-source
+  failures with circuit-breaker retry hints), and `recovery_hints[]`.
+  `ResolveWorkResult` is exported from the SDK's public surface.
+  The five per-source `enrichWorkMlc` / `enrichWorkSpotify` /
+  `enrichWorkYouTube` / `enrichWorkMusicBrainz` / `enrichWorkDiscogs`
+  methods remain available this release but are deprecated at the MCP
+  tool layer; the next minor will remove them from the SDK.
+- **ADR-179 Phase 2: `EnrichmentResource.resolvePerson(personId, options?)`.**
+  Outcome-shaped person resolver mirroring `resolveWork`. Wraps the new
+  `POST /admin/people/{id}/resolve` endpoint. Accepts an optional
+  `sources` whitelist (`isni` | `musicbrainz`) and `includeFuzzy` flag.
+  Returns `ResolvePersonResult` with the same applied/proposals/errors
+  shape. The legacy `PeopleResource.enrichFromISNI` /
+  `enrichFromMusicBrainz` methods remain available this release but
+  are deprecated at the MCP tool layer; the next minor will remove
+  them from the SDK.
+- **ADR-179 Phase 3: `EnrichmentResource.resolveRecording(recordingId, options?)`.**
+  Outcome-shaped recording resolver mirroring `resolveWork` /
+  `resolvePerson`. Wraps the new `POST /admin/recordings/{id}/resolve`
+  endpoint. Accepts an optional `sources` whitelist (`spotify` |
+  `youtube` | `musicbrainz` | `discogs`) and `includeFuzzy` flag.
+  Returns `ResolveRecordingResult` with the same applied/proposals/
+  errors shape. First recording-side enrichment surface on the SDK.
+  MusicBrainz + Discogs adapters are stubs server-side for now —
+  they surface eligibility via `sources_run` but make no external
+  calls until their corresponding cascade rules ship.
+- `/resolve` path added to `LONG_TIMEOUT_PATTERNS` so the fan-out (up
+  to five sequential external API calls) gets the 120s long-timeout
+  instead of the default 30s. Covers both the work and person resolver
+  routes.
+
+## [1.7.0] — 2026-04-16
+
+### Added
+
+- **ADR-178: `EnrichmentResource.proposeAgentResearch(input)`.** New
+  SDK method wraps the `POST /admin/enrichment-proposals` route that
+  backs the `pica_enrichment_propose` MCP tool (stdio in
+  `@withpica/mcp-server@2.17.0`, HTTP in
+  `@withpica/mcp-server-business@1.5.0`). Input is snake_case through-
+  out (matches the REST route, matches the agent-facing tool schema —
+  no case-translation layer). Response on success is `{ proposal_id,
+source: 'agent_research', rule_id: 'agent_research', status:
+'pending' }`. Five documented client-error shapes surface through
+  `ApiError`: `MISSING_SOURCE` (400), `MISSING_FIELDS` (400),
+  `INVALID_SOURCE_SHAPE` (400), `ENTITY_NOT_FOUND` (404),
+  `DUPLICATE_SUPPRESSED` (409). Consumers parse the error code from
+  the JSON response body inside the thrown `ApiError` — the MCP tool
+  layer lifts it into `structuredContent.code` so agents can reason
+  about failure shape without free-text parsing.
+
+## [1.6.0] — 2026-04-14
+
+### Added
+
+- **ADR-173: release-track primitives on `ReleasesResource`.** Five new
+  methods back the ADR-173 MCP tools: `attachTrack`, `listTracks`,
+  `detachTrack`, `reorderTracks`, `attachRecordingWithWork`. Routes map
+  to new admin endpoints under `/admin/releases/[id]/tracks` (and
+  sub-paths `/reorder`, `/detach`, `/attach-recording-with-work`).
+- **`WorksResource.listReleases` + `RecordingsResource.listReleases`.**
+  Back the new `releases` section on `pica_works_inspect` and
+  `pica_recordings_inspect` — each returns every release the entity
+  appears on with its track position.
+
+## [1.5.0] — 2026-04-14
+
+### Added
+
+- **ADR-174 Phase 2: `LabelsResource`** — new read-only SDK resource for
+  resolving label names to `organisations.id` (used as
+  `releases.label_organization_id`). `pica.labels.list({ query?, limit? })`
+  returns an array of `LabelOrganisation` rows (organisations with
+  `org_type='label'`). Exports the `LabelOrganisation` type.
+
+## [1.4.0] — 2026-04-11
+
+### Added
+
+- **ADR-166: YouTube import SDK methods** (`78da58344`)
+  - `ImportResource.youtubeLinkPreview(url)` — POSTs to
+    `/admin/import/youtube-link` with just `url`. Returns the preview
+    payload (items + classification + work match).
+  - `ImportResource.youtubeLinkImport(url, options)` — POSTs with
+    `confirm: true` plus optional `selectedVideoIds`, `targetWorkId`,
+    `overrideVersionType`. Returns the import result.
+- **ADR-163: Tier B enrichment proposal review SDK methods** (`ff9cf265a`)
+  - `EnrichmentResource.listEnrichmentProposals(params)` — GETs
+    `/admin/enrichment-proposals` with filter query params (`entity_type`,
+    `entity_id`, `rule_id`, `source`, `limit`, `offset`). Returns the
+    page of pending proposals.
+  - `EnrichmentResource.applyEnrichmentProposal(id, options)` — POSTs to
+    `/admin/enrichment-proposals/:id/apply` with `{ force, resolution_note }`.
+    For update proposals, drift detection runs first; if the entity has
+    changed since the proposal was created, the response is
+    `{ status: 'drift_detected', conflicts }` and nothing is written —
+    pass `force: true` on retry after reviewing the conflicts. For
+    create proposals a uniqueness check runs and cannot be forced.
+  - `EnrichmentResource.rejectEnrichmentProposal(id, options)` — POSTs
+    to `/admin/enrichment-proposals/:id/reject` with `{ resolution_note }`.
+    Content-hash suppression permanently blocks re-proposal of the same
+    exact content.
+
+### Notes
+
+- Two additive changes, no signature changes to existing methods. Minor
+  bump per semver.
+- Consumer packages pin `"@withpica/mcp-sdk": "^1.0.0"`, so the caret
+  range picks up `1.4.0` automatically.
+- Source additions landed earlier: YouTube methods in `78da58344`
+  (feat(adr-166): phase 4 — pica_import_youtube_link MCP tool + SDK
+  methods), Tier B proposal methods in `ff9cf265a` (feat(adr-163) phase
+  3c+3d).
+- Version bump carried in `ff97faa56` (feat(adr-163 phase 6): MCP HTTP
+  transport parity + version bumps). That commit shipped the bump
+  without its matching changelog entry — this is the follow-up commit
+  closing the discipline gap.
+
+## [1.3.0] — 2026-04-11
+
+### Added
+
+- **ADR-164: cascade control + observability SDK methods.**
+  - `runWorkCascade(workId)` — manually re-evaluate a work against every
+    ADR-164 cascade rule. POSTs to `/admin/works/:id/cascade-run`. Agents
+    can retry enrichment after a fix without waiting for the daily sweep.
+  - `runPersonCascade(personId)` — same for people. POSTs to
+    `/admin/people/:id/cascade-run`.
+  - `getCascadeHealth()` — snapshot of the in-process cascade failure +
+    outcome counters. GETs `/admin/cascade-health` (org-auth twin of the
+    operator-only `/api/internal/cascade-health` endpoint that uses
+    `CRON_SECRET`).
+
+### Notes
+
+- All three additions are backwards-compatible. Minor bump per semver.
+- All `@withpica/*` consumer packages pin `"@withpica/mcp-sdk": "^1.0.0"`,
+  so a `1.3.0` caret range picks up automatically — no transitive bumps.
+- Tagged in commit `edfbcb07b` (`chore(mcp-sdk): bump to 1.3.0`), which
+  also carried the matching `mcp-server@2.9.0` bump + rebuilt dist.
+- Source additions landed earlier in `38901f281` (ADR-164 audit
+  follow-ups).
+
+## [1.2.0] — 2026-04-10
+
+### Changed
+
+- Version bump carried in `7c4f5d24a` (`chore(adr-162): version bumps for
+npm publish`) alongside the ADR-162 subscription-based billing rollout.
+  No user-visible SDK API changes — the bump reflects the coupled release
+  of all `@withpica/*` packages under the new billing contract.
+
+## [1.1.0] — 2026-04-08
+
+### Changed
+
+- Carried in `91dd1c275` (`chore(adr-158c): version bumps for custody
+tool release (Phase 6b)`). Releases the custody-claim / custody-respond
+  / custody-history tool surface via coupled bumps across the MCP package
+  set.
+
+## [1.0.0] — 2026-04-07
+
+### Added
+
+- Initial public release. Package split out from the legacy monolithic
+  `mcp-server` in `e235aed40` (`feat(mcp): ADR-155 launch — publish 6
+packages, lobby-mode connect copy`). Provides the shared `PicaClient`
+  class that every `@withpica/mcp-server-*` package consumes for REST
+  access to PICA.
+
+> **Pre-changelog era:** before `1.0.0`, the SDK lived inline in
+> `@withpica/mcp-server` source. Version history for that era is
+> reconstructable via `git log --follow -- mcp-server-shared/mcp-sdk/`.
+
+[Unreleased]: https://github.com/withpica/pica/compare/ff97faa56...HEAD
+[1.4.0]: https://github.com/withpica/pica/compare/edfbcb07b...ff97faa56
+[1.3.0]: https://github.com/withpica/pica/compare/7c4f5d24a...edfbcb07b
+[1.2.0]: https://github.com/withpica/pica/compare/91dd1c275...7c4f5d24a
+[1.1.0]: https://github.com/withpica/pica/compare/e235aed40...91dd1c275
+[1.0.0]: https://github.com/withpica/pica/commit/e235aed40