@withpica/mcp-sdk 1.4.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

package/dist/index.d.ts

@@ -2,6 +2,107 @@
  * Lightweight PICA SDK client for MCP server
  * Uses the PICA API directly without external dependencies
  */
+/**
+ * ADR-179 resolver result shape. Mirrors the server-side
+ * `ResolveWorkResult` in `lib/services/enrichment-cascade/resolver.ts`.
+ * Duplicated here because this package has no type-sharing mechanism
+ * with the PICA monorepo; drift is caught by the holdout suite.
+ */
+export interface ResolveWorkResult {
+    entity_type: "work";
+    entity_id: string;
+    sources_run: Array<"mlc" | "spotify" | "youtube" | "musicbrainz" | "discogs">;
+    applied: Array<{
+        source: "mlc" | "spotify" | "youtube" | "musicbrainz" | "discogs";
+        rule_id: string;
+        fields: string[];
+        target_entity_type: "work";
+        target_entity_id: string;
+    }>;
+    proposals: Array<{
+        proposal_id: string;
+        source: "mlc" | "spotify" | "youtube" | "musicbrainz" | "discogs";
+        rule_id: string;
+        confidence: number | null;
+        field_count: number;
+        signals: Record<string, unknown> | null;
+    }>;
+    errors: Array<{
+        source: "mlc" | "spotify" | "youtube" | "musicbrainz" | "discogs";
+        rule_id?: string;
+        error_code: string;
+        retry_after_ms?: number;
+        message?: string;
+    }>;
+    recovery_hints: string[];
+}
+/**
+ * ADR-179 Phase 3 recording resolver result. Mirrors the server-side
+ * `ResolveRecordingResult` in `lib/services/enrichment-cascade/resolver.ts`.
+ */
+export interface ResolveRecordingResult {
+    entity_type: "recording";
+    entity_id: string;
+    sources_run: Array<"spotify" | "youtube" | "musicbrainz" | "discogs">;
+    applied: Array<{
+        source: "spotify" | "youtube" | "musicbrainz" | "discogs";
+        rule_id: string;
+        fields: string[];
+        target_entity_type: "recording";
+        target_entity_id: string;
+    }>;
+    proposals: Array<{
+        proposal_id: string;
+        source: "spotify" | "youtube" | "musicbrainz" | "discogs";
+        rule_id: string;
+        confidence: number | null;
+        field_count: number;
+        signals: Record<string, unknown> | null;
+    }>;
+    errors: Array<{
+        source: "spotify" | "youtube" | "musicbrainz" | "discogs";
+        rule_id?: string;
+        error_code: string;
+        retry_after_ms?: number;
+        message?: string;
+    }>;
+    recovery_hints: string[];
+}
+/**
+ * ADR-179 Phase 2 person resolver result. Mirrors the server-side
+ * `ResolvePersonResult` in `lib/services/enrichment-cascade/resolver.ts`.
+ * Duplicated here for the same reason as `ResolveWorkResult` — this
+ * package has no type-sharing mechanism with the PICA monorepo; drift
+ * is caught by the holdout suite.
+ */
+export interface ResolvePersonResult {
+    entity_type: "person";
+    entity_id: string;
+    sources_run: Array<"isni" | "musicbrainz">;
+    applied: Array<{
+        source: "isni" | "musicbrainz";
+        rule_id: string;
+        fields: string[];
+        target_entity_type: "person";
+        target_entity_id: string;
+    }>;
+    proposals: Array<{
+        proposal_id: string;
+        source: "isni" | "musicbrainz";
+        rule_id: string;
+        confidence: number | null;
+        field_count: number;
+        signals: Record<string, unknown> | null;
+    }>;
+    errors: Array<{
+        source: "isni" | "musicbrainz";
+        rule_id?: string;
+        error_code: string;
+        retry_after_ms?: number;
+        message?: string;
+    }>;
+    recovery_hints: string[];
+}
 interface CatalogStats {
     works: {
         total: number;
@@ -298,6 +399,18 @@ declare class BaseResource {
     protected apiKey: string;
     protected debug: boolean;
     constructor(baseUrl: string, apiKey: string, debug: boolean);
+    /**
+     * Vercel Deployment Protection bypass header for preview self-fetches.
+     *
+     * When the SDK is used server-side on a Vercel preview (e.g. the MCP
+     * HTTP route calling back into its own admin resolve routes),
+     * Vercel's edge wraps the internal call in deployment protection and
+     * 401s before the request reaches the route handler. "Protection
+     * Bypass for Automation" auto-injects VERCEL_AUTOMATION_BYPASS_SECRET
+     * at runtime; forward it as the documented header so self-fetches
+     * reach the actual route. Empty outside Vercel — safe no-op.
+     */
+    private getBypassHeaders;
     private fetchWithTimeout;
     private fetchWithRetry;
     protected request<T>(method: string, path: string, body?: any): Promise<T>;
@@ -330,6 +443,16 @@ declare class WorksResource extends BaseResource {
      * from the work side. Withdrawn links are filtered server-side.
      */
     listProductionAssets(workId: string): Promise<ProductionAssetLink[]>;
+    /**
+     * ADR-173 Decision 2: list every release this work appears on, with
+     * its track position. Distinct from listProductionAssets — this is
+     * release-context, not physical-asset provenance.
+     */
+    listReleases(workId: string): Promise<Array<{
+        release: Record<string, any>;
+        track_number: number;
+        disc_number: number | null;
+    }>>;
 }
 declare class PeopleResource extends BaseResource {
     list(params?: {
@@ -612,6 +735,16 @@ declare class RecordingsResource extends BaseResource {
      * from the recording side. Withdrawn links are filtered server-side.
      */
     listProductionAssets(recordingId: string): Promise<ProductionAssetLink[]>;
+    /**
+     * ADR-173 Decision 2: list every release this recording appears on,
+     * with its track position. Backs the `releases` section on
+     * pica_recordings_inspect.
+     */
+    listReleases(recordingId: string): Promise<Array<{
+        release: Record<string, any>;
+        track_number: number;
+        disc_number: number | null;
+    }>>;
 }
 declare class EnrichmentResource extends BaseResource {
     enrichWork(workId: string): Promise<any>;
@@ -623,6 +756,63 @@ declare class EnrichmentResource extends BaseResource {
     enrichWorkDiscogs(workId: string): Promise<any>;
     enrichWorkSpotify(workId: string): Promise<any>;
     enrichWorkYouTube(workId: string): Promise<any>;
+    /**
+     * ADR-179 outcome resolver — fan a work out across every eligible
+     * enrichment source and return a structured receipt.
+     *
+     * The orchestration lives server-side (see
+     * `lib/services/enrichment-cascade/resolver.ts`); this SDK method is
+     * the thin wrapper the MCP tool layer calls. Future Tasks-primitive
+     * conversion (ADR-171) will turn the request into a Task so agents
+     * receive per-source status events as each provider resolves. Today
+     * the shape is the final receipt only — callers treat the object
+     * returned here as that single terminal event.
+     *
+     *   sources:       optional whitelist. Omit to fan out to every
+     *                  eligible source (mlc, spotify, youtube,
+     *                  musicbrainz, discogs).
+     *   includeFuzzy:  defaults true. When false, Tier B cascade rules
+     *                  (fuzzy matches that would file review proposals)
+     *                  are skipped entirely.
+     */
+    resolveWork(workId: string, options?: {
+        sources?: Array<"mlc" | "spotify" | "youtube" | "musicbrainz" | "discogs">;
+        includeFuzzy?: boolean;
+    }): Promise<ResolveWorkResult>;
+    /**
+     * ADR-179 Phase 2 — person resolver. Fans a person across the two
+     * eligible identity-graph sources (ISNI + MusicBrainz) and returns
+     * a structured receipt in the same shape as `resolveWork`. Replaces
+     * the legacy `PeopleResource.enrichFromISNI` / `enrichFromMusicBrainz`
+     * calls at the MCP tool layer — those SDK methods stay available this
+     * release but are deprecated via `pica_people_enrich_*` returning
+     * `TOOL_DEPRECATED`.
+     *
+     *   sources:       optional whitelist. Omit to run both sources.
+     *                  Allowed: `isni` | `musicbrainz`.
+     *   includeFuzzy:  defaults true. When false, Tier B cascade rules
+     *                  (fuzzy matches that would file review proposals)
+     *                  are skipped entirely.
+     */
+    resolvePerson(personId: string, options?: {
+        sources?: Array<"isni" | "musicbrainz">;
+        includeFuzzy?: boolean;
+    }): Promise<ResolvePersonResult>;
+    /**
+     * ADR-179 Phase 3 — recording resolver. Fans a recording across eligible
+     * master-side sources (Spotify, YouTube, MusicBrainz, Discogs) and returns
+     * a structured receipt in the same shape as `resolveWork` / `resolvePerson`.
+     *
+     *   sources:       optional whitelist. Omit to run every eligible source.
+     *                  Allowed: `spotify` | `youtube` | `musicbrainz` | `discogs`.
+     *   includeFuzzy:  defaults true. When false, Tier B cascade rules
+     *                  (fuzzy matches that would file review proposals)
+     *                  are skipped entirely.
+     */
+    resolveRecording(recordingId: string, options?: {
+        sources?: Array<"spotify" | "youtube" | "musicbrainz" | "discogs">;
+        includeFuzzy?: boolean;
+    }): Promise<ResolveRecordingResult>;
     /**
      * ADR-164: manually re-evaluate a work against every cascade rule.
      * Idempotent — rules whose preconditions are already satisfied skip.
@@ -675,6 +865,42 @@ declare class EnrichmentResource extends BaseResource {
     rejectEnrichmentProposal(proposalId: string, options?: {
         resolution_note?: string;
     }): Promise<any>;
+    /**
+     * ADR-178: File a proposal sourced from open-web agent research.
+     *
+     * Distinct from cascade-sourced proposals. Every `proposed_fields`
+     * key must appear in at least one `sources[].fields` array —
+     * unsourced claims return a 400 with `code: "MISSING_SOURCE"` and
+     * the proposal is not persisted. The server hard-codes
+     * `source = 'agent_research'` and `rule_id = 'agent_research'`;
+     * callers omit both.
+     *
+     * Response codes carried through to the caller:
+     *   - 201: `{ proposal_id, source, rule_id, status }` (pending)
+     *   - 409 `DUPLICATE_SUPPRESSED`: identical content already filed
+     *   - 400 `MISSING_SOURCE`: uncited proposed field or empty sources
+     *   - 400 `MISSING_FIELDS`: proposed_fields was empty
+     *   - 400 `INVALID_SOURCE_SHAPE`: a source entry lacked url/fields/accessed_at
+     *   - 404 `ENTITY_NOT_FOUND`: entity_id not in caller's org
+     */
+    proposeAgentResearch(input: {
+        entity_type: "work" | "person" | "recording";
+        entity_id: string;
+        proposed_fields: Record<string, unknown>;
+        sources: Array<{
+            url: string;
+            fields: string[];
+            accessed_at: string;
+        }>;
+        confidence_score?: number | null;
+        rationale?: string;
+        proposal_action?: "update" | "create";
+    }): Promise<{
+        proposal_id: string;
+        source: "agent_research";
+        rule_id: "agent_research";
+        status: "pending";
+    }>;
     /** Preview what a Spotify URL would do — delegates to streaming-link */
     spotifyUrlPreview(url: string): Promise<any>;
     /** Execute import/enrich from a Spotify URL — delegates to streaming-link */
@@ -717,6 +943,16 @@ declare class SettingsResource extends BaseResource {
     storageConfig(): Promise<any>;
     orgProfile(): Promise<any>;
     userProfile(): Promise<any>;
+    /**
+     * Update the authenticated user's privacy / marketing-preference flags.
+     * Parity with ADR-183's settings-tab toggles — exposes the same fields
+     * the web UI writes, so an agent can unsubscribe on the user's behalf
+     * without leaving the conversation. ADR-184 slice 5.
+     */
+    updatePrivacySettings(params: {
+        receive_news_announcements?: boolean;
+        receive_monthly_digest?: boolean;
+    }): Promise<any>;
 }
 declare class CalendarResource extends BaseResource {
     getEvents(params: {
@@ -1206,6 +1442,11 @@ declare class ProjectsResource extends BaseResource {
     create(data: Record<string, any>): Promise<any>;
     update(id: string, data: Record<string, any>): Promise<any>;
     delete(id: string): Promise<any>;
+    attachWork(projectId: string, data: {
+        work_id: string;
+        project_day?: number | null;
+        notes?: string | null;
+    }): Promise<any>;
 }
 declare class SplitSheetsResource extends BaseResource {
     listForWork(workId: string): Promise<any>;
@@ -1224,10 +1465,21 @@ declare class PublishersResource extends BaseResource {
         query?: string;
         limit?: number;
     }): Promise<any>;
-    create(data: {
-        name: string;
-        ipi?: string;
-    }): Promise<any>;
+    create(data: Record<string, unknown>): Promise<any>;
+}
+export interface LabelOrganisation {
+    id: string;
+    name: string;
+    display_name: string | null;
+    country: string | null;
+    website: string | null;
+    verification_status: string | null;
+}
+declare class LabelsResource extends BaseResource {
+    list(params?: {
+        query?: string;
+        limit?: number;
+    }): Promise<LabelOrganisation[]>;
 }
 declare class ReleasesResource extends BaseResource {
     list(params?: {
@@ -1237,6 +1489,48 @@ declare class ReleasesResource extends BaseResource {
     create(data: Record<string, any>): Promise<any>;
     update(id: string, data: Record<string, any>): Promise<any>;
     delete(id: string): Promise<any>;
+    /**
+     * ADR-173: attach a recording and/or work to a release at a
+     * specific (disc, track) position. Idempotent on position.
+     */
+    attachTrack(releaseId: string, data: {
+        recording_id?: string | null;
+        work_id?: string | null;
+        track_number: number;
+        disc_number?: number;
+    }): Promise<any>;
+    /**
+     * ADR-173: list tracks on a release in (disc, track) order with
+     * inlined work + recording summary fields.
+     */
+    listTracks(releaseId: string): Promise<any>;
+    /**
+     * ADR-173: soft-confirmation detach by position. Call without
+     * confirm:true to get a preview; call with confirm:true to execute.
+     */
+    detachTrack(releaseId: string, data: {
+        track_number: number;
+        disc_number?: number;
+        confirm?: boolean;
+    }): Promise<any>;
+    /**
+     * ADR-173: transactional positional reorder. Input is the full
+     * new order as [{ track_id, track_number, disc_number }].
+     */
+    reorderTracks(releaseId: string, newOrder: Array<{
+        track_id: string;
+        track_number: number;
+        disc_number?: number;
+    }>): Promise<any>;
+    /**
+     * ADR-173 Decision 4: compound attach that resolves the
+     * recording's work_id server-side before creating the track row.
+     */
+    attachRecordingWithWork(releaseId: string, data: {
+        recording_id: string;
+        track_number: number;
+        disc_number?: number;
+    }): Promise<any>;
 }
 declare class SessionsResource extends BaseResource {
     list(params?: {
@@ -1416,6 +1710,7 @@ export declare class PicaClient {
     splitSheets: SplitSheetsResource;
     recordingSplits: RecordingSplitsResource;
     publishers: PublishersResource;
+    labels: LabelsResource;
     agreementTemplates: AgreementTemplatesResource;
     producerAgreements: ProducerAgreementsResource;
     workForHire: WorkForHireResource;