@withpica/mcp-sdk 1.47.0 → 1.48.0

package/CHANGELOG.md

@@ -11,6 +11,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.48.0] - 2026-06-25
+
+### Added
+
+- **`resolveRelease(id, body)`** → `POST /admin/releases/:id/resolve`, plus the
+  `ResolveReleaseResult` type. Backs `pica_resolve_release` (release-grain
+  Spotify gap-fill enrichment through the authority gate).
+- **`CatalogHealthResource`** — `catalogHealth()` (`GET /admin/catalog-health`,
+  whole-catalog completeness + cleanliness verdict), `catalogHealthPlan(body)`
+  (derives an actionable fix-plan + `planToken`), and `catalogHealthFix(body)`
+  (applies accepted `actionIds` / `all_safe_auto`, returning honest
+  `applied` / `skipped`). Plus the `CatalogHealth*` result types. Back
+  `pica_catalog_health` / `_plan` / `_fix` (ADR-272 / ADR-273).
+- **`DocumentsResource`** — `listCatalog(params)`, `read(id, params)` (bounded
+  content read), and `link(id, entity_type, entity_id)` (provenance link to a
+  work / person / recording). Backs the ADR-274 document bridge
+  (`pica_documents_list` / `_read` / `_link`).
+
 ## [1.47.0] - 2026-06-22
 
 ### Added

package/dist/index.d.ts

@@ -92,6 +92,42 @@ export interface ResolveRecordingResult {
     skipped_lower_authority: SkippedAuthorityReceipt[];
     recovery_hints: string[];
 }
+/**
+ * Release resolver result. Mirrors the server-side `ResolveReleaseResult`
+ * in the resolver service. Duplicated here — no type-sharing mechanism with
+ * the PICA monorepo; drift is caught by the holdout suite.
+ */
+export interface ResolveReleaseResult {
+    entity_type: "release";
+    entity_id: string;
+    /** v1 is Spotify-only; field narrowed to reflect the single eligible source. */
+    sources_run: Array<"spotify">;
+    applied: Array<{
+        source: "spotify";
+        rule_id: string;
+        fields: string[];
+        target_entity_type: "release";
+        target_entity_id: string;
+    }>;
+    proposals: Array<{
+        proposal_id: string;
+        source: "spotify";
+        rule_id: string;
+        confidence: number | null;
+        field_count: number;
+        signals: Record<string, unknown> | null;
+    }>;
+    errors: Array<{
+        source: "spotify";
+        rule_id?: string;
+        error_code: string;
+        retry_after_ms?: number;
+        message?: string;
+    }>;
+    overwrote: OverwriteReceipt[];
+    skipped_lower_authority: SkippedAuthorityReceipt[];
+    recovery_hints: string[];
+}
 /**
  * ADR-179 Phase 2 person resolver result. Mirrors the server-side
  * `ResolvePersonResult` in `lib/services/enrichment-cascade/resolver.ts`.
@@ -278,6 +314,7 @@ interface Recording {
     isrc?: string;
     duration_seconds?: number;
     work_id?: string;
+    notes?: string | null;
     created_at: string;
     updated_at: string;
 }
@@ -1009,10 +1046,7 @@ declare class MultimediaResource extends BaseResource {
         person_id?: string;
         limit?: number;
         offset?: number;
-    }): Promise<{
-        data: MultimediaItem[];
-        count: number;
-    }>;
+    }): Promise<PaginatedResult<MultimediaItem>>;
     create(data: Partial<MultimediaItem>): Promise<MultimediaItem>;
     importFromUrl(params: {
         url: string;
@@ -1305,6 +1339,22 @@ declare class EnrichmentResource extends BaseResource {
          */
         force?: boolean;
     }): Promise<ResolveRecordingResult>;
+    /**
+     * Resolve a release against every eligible enrichment source.
+     * v1 is Spotify-only — a release resolve always re-checks Spotify and
+     * gap-fills empty fields via the authority gate (no idempotence stamps
+     * exist for releases). `force` is accepted for API parity but has no
+     * distinct effect here.
+     *
+     * @param releaseId  UUID of the release to resolve.
+     * @param options
+     *   sources:  optional whitelist. v1 supports `spotify` only.
+     *   force:    accepted for parity; no distinct effect for releases.
+     */
+    resolveRelease(releaseId: string, options?: {
+        sources?: Array<"spotify">;
+        force?: boolean;
+    }): Promise<ResolveReleaseResult>;
     /**
      * ADR-164: manually re-evaluate a work against every cascade rule.
      * Idempotent — rules whose preconditions are already satisfied skip.
@@ -1443,10 +1493,107 @@ declare class RegistrationResource extends BaseResource {
     getCoverage(): Promise<any>;
     getWorkCascadeStatus(workId: string): Promise<any>;
 }
+export interface CatalogHealthItem {
+    grain: "work" | "recording" | "release" | "person";
+    issue: string;
+    dimension: "completeness" | "cleanliness";
+    severity: "high" | "medium" | "low";
+    count: number;
+    sampleIds: string[];
+    truncated: boolean;
+    needsScope: string | null;
+    actionableByCaller: boolean;
+}
+export interface CatalogHealthVerdict {
+    score: number | null;
+    dimensionScores: {
+        completeness: number | null;
+        cleanliness: number | null;
+    };
+    assessed: string[];
+    notAssessed: string[];
+    items: CatalogHealthItem[];
+    generatedAt: string;
+}
+export interface CatalogHealthPlanAction {
+    actionId: string;
+    issue: string;
+    actionKind: string;
+    disposition: "auto" | "propose";
+    destructive: boolean;
+    needsScope: string;
+    actionableByCaller: boolean;
+    entityRefs: {
+        type: string;
+        id: string;
+    }[];
+    preview: Record<string, unknown>;
+}
+export interface CatalogHealthResidualItem {
+    issue: string;
+    count: number;
+    reason: string;
+    next_tool?: string;
+}
+export interface CatalogHealthPlan {
+    score: number | null;
+    dimensionScores: {
+        completeness: number | null;
+        cleanliness: number | null;
+    };
+    targetScore: number;
+    actions: CatalogHealthPlanAction[];
+    residual: CatalogHealthResidualItem[];
+    planToken: string;
+    generatedAt: string;
+}
+export interface CatalogHealthAppliedResult {
+    actionId: string;
+    met: true;
+    summary: string;
+}
+export interface CatalogHealthSkippedResult {
+    actionId: string;
+    met: false;
+    reason: "scope_denied" | "guard_blocked" | "stale" | "not_accepted";
+}
+export interface CatalogHealthFixResult {
+    applied: CatalogHealthAppliedResult[];
+    skipped: CatalogHealthSkippedResult[];
+    verdict: unknown;
+    outcomesRecorded: number;
+}
 declare class HealthResource extends BaseResource {
     getWorksHealth(): Promise<any>;
     getLowScoreWorks(): Promise<any>;
     getWorkCompleteness(workId: string): Promise<any>;
+    /**
+     * ADR-272 — org-scoped catalog health verdict (completeness + cleanliness
+     * with a ranked punch-list). The route returns `{ success, data: verdict }`;
+     * BaseResource.request unwraps the `{ success, data }` envelope via
+     * `data.data || data`, so this resolves to the verdict object directly
+     * (NOT a second `.data` — the recurring double-unwrap trap). Typed against
+     * the UNWRAPPED shape.
+     */
+    catalogHealth(): Promise<CatalogHealthVerdict>;
+    /**
+     * ADR-273 — scope-gated fix plan. POSTs to /admin/catalog-health/plan,
+     * returns a CatalogHealthPlan with actionable fix-actions + planToken.
+     * Mutates nothing.
+     */
+    catalogHealthPlan(body: {
+        targetScore?: number;
+        only?: string[];
+    }): Promise<CatalogHealthPlan>;
+    /**
+     * ADR-273 — apply accepted fix actions from a prior plan. Requires planToken
+     * from catalogHealthPlan; accept is a list of actionIds (or "all_safe_auto").
+     * Returns honest per-action met/unmet plus a fresh verdict.
+     */
+    catalogHealthFix(body: {
+        planToken: string;
+        accept: string[];
+    }): Promise<CatalogHealthFixResult>;
 }
 declare class DashboardResource extends BaseResource {
     discoveries(params?: {
@@ -2148,6 +2295,13 @@ declare class ExportResource extends BaseResource {
     }): Promise<any>;
     industryReady(params?: {
         work_ids?: string[];
+        /**
+         * "zip" (default) returns a signed-URL JSON envelope to the generated ZIP
+         * on S3. "json" returns the structured export data inline — reachable by
+         * sandboxed agents whose allowlist excludes the S3 host (ops_issue
+         * 8662c489).
+         */
+        format?: "zip" | "json";
     }): Promise<any>;
     catalogAssetReport(params: {
         sections: {
@@ -2503,6 +2657,20 @@ declare class ImportResource extends BaseResource {
 }
 declare class DocumentsResource extends BaseResource {
     analyse(id: string): Promise<Record<string, unknown>>;
+    listCatalog(params?: {
+        parsed_status?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<{
+        documents: unknown[];
+        total: number;
+        has_more: boolean;
+    }>;
+    read(id: string, params?: {
+        offset?: number;
+        max_chars?: number;
+    }): Promise<Record<string, unknown>>;
+    link(id: string, entity_type: string, entity_id: string): Promise<unknown>;
 }
 interface CollaboratorInvite {
     id: string;