@withpica/mcp-sdk 1.39.0 → 1.40.0

package/CHANGELOG.md

@@ -11,6 +11,78 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.40.0] - 2026-06-12
+
+ADR-264 WS2 verify-before-assert + WS4 bulk recording credits + ADR-268 WS1
+party claims / WS2 label identifiers / WS5 ownership transfer types. Removes
+the never-functional `TeamResource`.
+
+### Changed
+
+- **`RecordingCustodyResource.assign`** now accepts the ownership transfer
+  types `assignment` and `full_transfer` (ADR-268 WS5, the ADR-262
+  fast-follow): the `transfer_type` union widens from
+  `delivery|license|admin_grant` to all five types. Ownership legs also move
+  the recording's master ownership splits append-only inside the same
+  transaction (the transferor's active era closes, the transferee's opens;
+  the credit layer never moves). Ambiguous or over-share partial transfers
+  are refused as client-recoverable 400s
+  (`PARTIAL_TRANSFER_AMBIGUOUS` / `INSUFFICIENT_TRANSFEROR_SHARE` /
+  `INVALID_PERCENTAGE`).
+- **`LabelsResource.create`** accepts an optional `identifiers` object
+  (`musicbrainz_label_id` / `isni` / `label_code` / `discogs_label_id` /
+  `wikidata_id` / `deezer_label_id`) — ADR-268 WS2 identifier-first dedup;
+  `LabelOrganisation` gains `global_label_id` (the bridge to the resolved
+  global label identity).
+
+### Removed
+
+- **`TeamResource` (`client.team.*` — list/get/invite/update/remove)** —
+  existed solely to back the `pica_team_*` MCP tools, which were removed
+  2026-06-11 (founder decision). `/api/admin/team/*` is session-only by
+  design (ADR-248: team membership is human-only), so every bearer SDK call
+  through this resource always received a hard 401; removal is honesty, not
+  a regression. Team membership is managed by humans in `/settings`.
+
+### Added
+
+- **`PartyClaimsResource` (`client.partyClaims.*`)** — ADR-268 WS1.
+  `invite({target_organisation_id, invited_email, release_id?, recording_id?})`
+  POSTs `/admin/party-claims` (send a claim invite for an unclaimed party
+  org; resolves the unwrapped `{invite, disputed, claim_url}` object) and
+  `list({target_organisation_id?, status?, limit?})` GETs the calling org's
+  sent claims. Backs the new `pica_party_claim_invite` /
+  `pica_party_claim_status` tools.
+
+- **`RecordingCreditsResource.bulkUpdate(input)`** — ADR-264 WS4 prerequisite.
+  POST `/admin/recording-credits/bulk` with exactly one of `release_id`
+  (targets every recording on the release's tracklist) / `recording_ids`,
+  plus the `credits[]` set applied to every target recording and optional
+  `dry_run`. Returns per-row `created` / `skipped_existing` (or
+  `would_create` / `would_skip_existing` on dry-run) results plus summary
+  counts. Typed against the unwrapped route payload.
+- **`WorksResource.verifyRegistrations(input)`** — ADR-264 WS2 verify-before-assert.
+  POST `/admin/works/verify-registrations` with `work_ids` (1-25), `mode`
+  (`"check"` runs an MLC lookup per work; `"confirm_unregistered"` records the
+  user's own assertion, optional `society_code`). Returns per-work results
+  (`already_registered` / `found_registered` / `verified_absent` /
+  `lookup_failed` / `insufficient_identifiers` / `confirmed` / `not_found`)
+  plus summary counts. Lookup errors and unmatchable works write nothing.
+
+## [1.39.1] - 2026-06-10
+
+ADR-264 WS1.3 type widening — releases/recordings dedup + merge coverage.
+
+### Changed
+
+- **`DuplicatesResource.findDuplicates`** param widened from
+  `"works" | "people"` → `"works" | "people" | "releases" | "recordings"` to
+  match the backend enum (ISRC-keyed recording groups, UPC-keyed release groups).
+- **`DuplicatesResource.merge`** `entityType` param widened from
+  `"work" | "person"` → `"work" | "person" | "recording" | "release"` so
+  callers can merge recording/release duplicates via the same SDK method.
+  Type-only widening; no new HTTP endpoints or methods.
+
 ## [1.39.0] - 2026-06-10
 
 ADR-265 release parties and invites — label/distributor org creation + recording/release-grain invite targets.
@@ -29,6 +101,21 @@ ADR-265 release parties and invites — label/distributor org creation + recordi
   enforces the invariant. The `CollaboratorInvite` row type's `work_id` is now
   nullable, with optional `recording_id` / `release_id`.
 
+### Fixed
+
+- **`labels.list` double-unwrap** — `BaseResource.request()` auto-unwraps the
+  route's `{ success, data }` envelope, but `labels.list` read `.data` a second
+  time off the already-unwrapped array, so it returned `[]` on every call —
+  `pica_labels_query` had returned "Found 0 labels" regardless of catalog
+  state since 1.34.x. Now tolerates both the raw array and the envelope
+  (same class and fix pattern as the 1.37.1 `listEnquiries` fix).
+- **`labels.create` envelope handling** — same double-read: on the live wire
+  `request()` returns the unwrapped label object, so the old
+  `{ data, already_existed }` return type was never populated. `create` now
+  resolves the label object directly (or `null`), with `already_existed`
+  carried inside it (the route duplicates it into `data` so the dedup signal
+  survives the unwrap).
+
 ## [1.38.0] - 2026-06-10
 
 ADR-264 WS1 trust floor support.

package/dist/index.d.ts

@@ -730,6 +730,30 @@ declare class WorksResource extends BaseResource {
             certificate_id?: string;
         } | null;
     }>;
+    /**
+     * ADR-264 WS2 — verify (or confirm) registration status for up to 25
+     * works. mode "check" runs an MLC lookup per work and records what the
+     * lookup proved (found → positive society fact; clean not-found →
+     * negative assertion); mode "confirm_unregistered" records the user's
+     * own assertion (society_code optional — omitted means "not registered
+     * anywhere"). Lookup errors and unmatchable works write nothing.
+     */
+    verifyRegistrations(input: {
+        work_ids: string[];
+        mode: "check" | "confirm_unregistered";
+        society_code?: string;
+    }): Promise<{
+        mode: "check" | "confirm_unregistered";
+        results: Array<{
+            work_id: string;
+            result: "already_registered" | "found_registered" | "verified_absent" | "lookup_failed" | "insufficient_identifiers" | "confirmed" | "not_found";
+            society_code?: string | null;
+            external_id?: string;
+            query_kind?: "iswc" | "title_writer_ipi" | "title_artist_name";
+            detail?: string;
+        }>;
+        summary: Record<string, number>;
+    }>;
 }
 declare class PeopleResource extends BaseResource {
     list(params?: {
@@ -1100,13 +1124,6 @@ declare class NotesResource extends BaseResource {
     }): Promise<any>;
     delete(id: string): Promise<void>;
 }
-declare class TeamResource extends BaseResource {
-    list(): Promise<any>;
-    get(id: string): Promise<any>;
-    invite(data: Record<string, any>): Promise<any>;
-    update(id: string, data: Record<string, any>): Promise<any>;
-    remove(id: string): Promise<any>;
-}
 declare class RecordingsResource extends BaseResource {
     list(params?: {
         limit?: number;
@@ -1381,8 +1398,8 @@ declare class DashboardResource extends BaseResource {
     /**
      * Actionable items projection — `{class, entity_id, entity_type,
      * entity_label, failure_mode, urgency: {score, components,
-     * model_version}, drill_down_skill, suggested_skill (alias, slated
-     * for removal)}` per row, sorted by `urgency.score` desc, capped at
+     * model_version}, drill_down_skill}` per row (the suggested_skill
+     * alias was removed 2026-06-11), sorted by `urgency.score` desc, capped at
      * `limit`. Backed by the shared actionable-items source so counts
      * agree with `pica_dashboard_briefing.critical_issues_total` and
      * `pica_count_explain.sources[].count` for the same org/moment.
@@ -2083,8 +2100,8 @@ declare class ExportResource extends BaseResource {
     }): Promise<any>;
 }
 declare class DuplicatesResource extends BaseResource {
-    findDuplicates(entityType: "works" | "people"): Promise<any>;
-    merge(entityType: "work" | "person", winnerId: string, loserIds: string[]): Promise<any>;
+    findDuplicates(entityType: "works" | "people" | "releases" | "recordings"): Promise<any>;
+    merge(entityType: "work" | "person" | "recording" | "release", winnerId: string, loserIds: string[]): Promise<any>;
 }
 declare class EntityContextResource extends BaseResource {
     getWorkFull(workId: string): Promise<Record<string, unknown>>;
@@ -2431,6 +2448,27 @@ interface CollaboratorInvite {
     created_at: string;
     updated_at: string;
 }
+/**
+ * ADR-264 W2d: response shape for POST /admin/collaborators/invite.
+ * The route appends person identity fields so the MCP tool can evaluate
+ * the collaborator_missing_identifiers hint without a second round-trip.
+ *
+ * person_id is null when the recipient is a brand-new person (not yet in the
+ * people table — they are created on invite acceptance, not at send time).
+ * has_ipi / has_isni are false when person_id is null or when the lookup
+ * fails (conservative defaults: never suppress the hint on uncertainty).
+ */
+export interface CollaboratorInviteResponse extends Record<string, unknown> {
+    /** The created collaboration_invites row id. */
+    id: string;
+    /** Resolved people.id for the recipient in the caller's org, if they already
+     *  exist. null for brand-new invitees. */
+    person_id: string | null;
+    /** True if the person already has an IPI entry in person_identifiers. */
+    has_ipi: boolean;
+    /** True if the person already has an ISNI entry in person_identifiers. */
+    has_isni: boolean;
+}
 declare class CollaboratorsResource extends BaseResource {
     invite(params: {
         /** ADR-265: exactly one of workId / recordingId / releaseId. */
@@ -2452,7 +2490,7 @@ declare class CollaboratorsResource extends BaseResource {
             kind: "email" | "handle";
             value: string;
         };
-    }): Promise<Record<string, unknown>>;
+    }): Promise<CollaboratorInviteResponse>;
     listInvites(params?: {
         status?: "pending" | "verified" | "confirmed" | "expired" | "cancelled" | "disputed";
         workId?: string;
@@ -2739,6 +2777,42 @@ export interface RecordingCreditCreateInput {
     display_order?: number;
     notes?: string | null;
 }
+export interface RecordingCreditsBulkCreditInput {
+    credited_name: string;
+    role: string;
+    person_id?: string | null;
+    split_percentage?: number | null;
+    split_type?: string | null;
+    display_order?: number;
+    notes?: string | null;
+}
+export interface RecordingCreditsBulkUpdateInput {
+    /** Target every recording on this release. Exactly one of release_id / recording_ids. */
+    release_id?: string;
+    recording_ids?: string[];
+    /** The credit set applied to EVERY target recording. */
+    credits: RecordingCreditsBulkCreditInput[];
+    /** Preview the create/skip decision set without writing. */
+    dry_run?: boolean;
+}
+export type RecordingCreditsBulkRowStatus = "created" | "skipped_existing" | "would_create" | "would_skip_existing";
+export interface RecordingCreditsBulkRowResult {
+    recording_id: string;
+    credited_name: string;
+    role: string;
+    status: RecordingCreditsBulkRowStatus;
+    credit_id?: string;
+}
+export interface RecordingCreditsBulkUpdateResult {
+    dry_run: boolean;
+    target_recording_count: number;
+    total_rows: number;
+    created: number;
+    skipped_existing: number;
+    would_create: number;
+    would_skip_existing: number;
+    results: RecordingCreditsBulkRowResult[];
+}
 declare class RecordingCreditsResource extends BaseResource {
     list(recordingId: string): Promise<RecordingCredit[]>;
     create(recordingId: string, input: RecordingCreditCreateInput): Promise<RecordingCredit>;
@@ -2754,6 +2828,13 @@ declare class RecordingCreditsResource extends BaseResource {
      * success. AC-2 strict semantics for pica_credit_remove.
      */
     atomicRemove(recordingId: string, creditId: string): Promise<AtomicCreditResult>;
+    /**
+     * ADR-264 WS4 prerequisite — apply one credit set across many recordings
+     * (a release's tracklist via release_id, or an explicit recording_ids
+     * list) in a single call. Existing (recording, credited_name, role) rows
+     * are skipped, never overwritten; dry_run previews the same decision set.
+     */
+    bulkUpdate(input: RecordingCreditsBulkUpdateInput): Promise<RecordingCreditsBulkUpdateResult>;
 }
 export type ShareTraceEntityType = "work" | "recording" | "person";
 export interface ShareTraceQuery {
@@ -2908,11 +2989,25 @@ export interface LabelOrganisation {
     country: string | null;
     website: string | null;
     verification_status: string | null;
+    org_type: string;
+    contact_email?: string | null;
+    /** ADR-268 WS2 bridge to the enrichment-side global label identity. */
+    global_label_id?: string | null;
+}
+/** External label identifiers accepted by labels.create (ADR-268 WS2). */
+export interface LabelIdentifiers {
+    musicbrainz_label_id?: string;
+    isni?: string;
+    label_code?: string;
+    discogs_label_id?: string;
+    wikidata_id?: string;
+    deezer_label_id?: string;
 }
 declare class LabelsResource extends BaseResource {
     list(params?: {
         query?: string;
         limit?: number;
+        org_type?: "label" | "distributor";
     }): Promise<LabelOrganisation[]>;
     create(params: {
         name: string;
@@ -2920,13 +3015,62 @@ declare class LabelsResource extends BaseResource {
         country?: string;
         website?: string;
         contact_email?: string;
-    }): Promise<{
-        success?: boolean;
-        data?: LabelOrganisation & {
-            org_type: string;
-        };
+        /**
+         * ADR-268 WS2: when supplied, server-side dedup is identifier-based —
+         * an org already bridged to the resolved global label identity is
+         * returned (already_existed) even if the name differs.
+         */
+        identifiers?: LabelIdentifiers;
+    }): Promise<(LabelOrganisation & {
+        org_type: string;
         already_existed?: boolean;
-    }>;
+    }) | null>;
+}
+export interface PartyClaimInviteSummary {
+    id: string;
+    organisation_id: string;
+    source: "invite" | "unsolicited";
+    invited_by_organisation_id: string | null;
+    invited_email: string;
+    status: string;
+    expires_at: string | null;
+    claimed_at: string | null;
+    claim_code: string | null;
+    release_id: string | null;
+    recording_id: string | null;
+    created_at: string;
+    organisation?: {
+        id: string;
+        name: string;
+        org_type: string;
+        verification_status: string | null;
+    };
+}
+export interface PartyClaimInviteResult {
+    invite: PartyClaimInviteSummary;
+    disputed: boolean;
+    claim_url: string | null;
+}
+/**
+ * ADR-268 WS1 — party org claim flow. `invite()` sends an artist-anchored
+ * claim invite for an unclaimed label/distributor/publisher org;
+ * `list()` reads the claims the calling org has sent.
+ *
+ * Typed against the UNWRAPPED reality (ADR-265 lesson): BaseResource.request
+ * auto-unwraps the `{success,data}` envelope, so methods see `data` itself.
+ */
+declare class PartyClaimsResource extends BaseResource {
+    invite(params: {
+        target_organisation_id: string;
+        invited_email: string;
+        release_id?: string;
+        recording_id?: string;
+    }): Promise<PartyClaimInviteResult | null>;
+    list(params?: {
+        target_organisation_id?: string;
+        status?: string;
+        limit?: number;
+    }): Promise<PartyClaimInviteSummary[]>;
 }
 declare class ReleasesResource extends BaseResource {
     list(params?: {
@@ -3189,17 +3333,19 @@ declare class CustodyResource extends BaseResource {
 }
 declare class RecordingCustodyResource extends BaseResource {
     /**
-     * Assign (transfer) custody of a recording. Admin/owner only. v1 supports
-     * control/possession transfer types only (delivery|license|admin_grant);
-     * ownership transfer (assignment|full_transfer) is a fast-follow and the
-     * route/service reject it. At least one custodian target must be supplied
-     * (org, global publisher, or global creator).
+     * Assign (transfer) custody of a recording. Admin/owner only.
+     * Control/possession types (delivery|license|admin_grant) leave ownership
+     * unchanged. Ownership types (assignment|full_transfer — ADR-268 WS5) also
+     * move the master ownership splits append-only in the same transaction:
+     * the transferor's active era closes, the transferee's opens; ambiguous or
+     * over-share partial transfers are refused (400). At least one custodian
+     * target must be supplied (org, global publisher, or global creator).
      */
     assign(body: {
         recording_id: string;
         percentage: number;
         territory: string;
-        transfer_type: "delivery" | "license" | "admin_grant";
+        transfer_type: "delivery" | "license" | "admin_grant" | "assignment" | "full_transfer";
         reason: string;
         new_custodian_org_id?: string | null;
         new_custodian_global_publisher_id?: string | null;
@@ -3376,7 +3522,6 @@ export declare class PicaClient {
     sessions: SessionsResource;
     assets: AssetsResource;
     notes: NotesResource;
-    team: TeamResource;
     projects: ProjectsResource;
     releases: ReleasesResource;
     splitSheets: SplitSheetsResource;
@@ -3387,6 +3532,7 @@ export declare class PicaClient {
     audioPipelineStatus: AudioPipelineStatusResource;
     publishers: PublishersResource;
     labels: LabelsResource;
+    partyClaims: PartyClaimsResource;
     agreementTemplates: AgreementTemplatesResource;
     producerAgreements: ProducerAgreementsResource;
     workForHire: WorkForHireResource;