@withpica/mcp-sdk 3.21.0 → 3.23.0

package/CHANGELOG.md

@@ -11,6 +11,70 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.23.0] - 2026-10-04
+
+### Added
+
+- `recordingSplits.edit(recordingId, splitId, data)` (PATCH) and
+  `recordingSplits.end(recordingId, splitId, { end_date?, notes? })` (POST
+  `.../splits/{splitId}/end`), returning the whole envelope — `data` plus
+  `previous`, `changed_fields` and `verification_cleared`
+  (`RecordingSplitEditEnvelope`).
+- `people.splitIdentityPreview(id)` and `people.splitIdentity(id, body)` over
+  `GET` / `POST /admin/people/{id}/split-identity` — give one person a new
+  global identity when two people share one; only the identifiers and
+  unattributed split rows the caller names move.
+- **`profileClaims` resource** — `invite({ person_ids, confirm })` (POST
+  `/admin/people/claim-invites`; a preview unless `confirm`) and
+  `status({ person_ids?, limit? })` (GET `/admin/profile-claims`), with the
+  `ProfileClaimInviteResult` and `ProfileClaimState` types.
+
+- `imports.listForwardedEmails({ limit, offset })` and
+  `imports.getForwardedEmail(id)` over `GET /admin/email-intake/forwarded`
+  (+ `/[id]`), with the `ForwardedEmailSummary` / `ForwardedEmailDetail` /
+  `ForwardedEmailList` types (`sender_trusted`, `content_notice`, and a
+  `not_filed` source for an email that reached the org but could not be
+  queued).
+- `credits.atomicUpdate` accepts `person_id` (link a name-only credit to a
+  person, or move a credit to a different person) and
+  `confirm_name_mismatch`, and returns `person_change` (`kind`,
+  `previous_person_id`, `attestation_reset`, `attestation_status`, `message`)
+  when the patch changed who the credit is for. New `CreditPersonChange`
+  type. `attestation_reset` is true when the change cleared a confirmation,
+  dispute or decline.
+
+## [3.22.0] - 2026-09-30
+
+### Added
+
+- `integrity.waive` accepts `kind` (`not_applicable` | `restricted`) for the
+  platform-presence codes `PLATFORM_SPOTIFY` / `PLATFORM_YOUTUBE` /
+  `PLATFORM_APPLE_MUSIC`, and returns the work's re-scored `completeness`
+  for them; `integrity.revokeWaiver` now returns the route's answer
+  (`{ id, revoked, completeness? }`) instead of `void`.
+- `PlatformWaiverCode` / `PlatformWaiverKind` types; `IntegrityGapCode` gains
+  `WORK_NO_MASTER`, `WORK_SPLITS_ABSENT`, `WORK_SPLITS_INVALID`.
+
+### Deprecated
+
+- `Work.is_verified` is now optional and deprecated. `works` has no such
+  column (no applied migration adds one), so works responses do not carry it;
+  PICA keeps no work-level verified flag. Remove at the next major, with
+  `works.verify`.
+- `rights.statements()`, `rights.statement(incomeId)`, `rights.recordIncome(body)`,
+  `rights.societyChecks(workId)` and `rights.measures()` — ADR-321 Phase 3
+  (distribution, computed and not paid), over `GET/POST /admin/rights-income`,
+  `GET /admin/rights-income/{id}`, `GET /admin/rights-statements/society` and
+  `GET /admin/rights-statements/measures`. All need finance access.
+
+### Fixed
+
+- `syncPlacements.addSource` posts to `/admin/sync-placements/{id}/cite`, the
+  route that exists; it posted to `/sources`, which has never existed, so
+  every call 404'd.
+- `assets.marketCheck` sends POST, the only verb its route serves; it sent
+  GET and got 405.
+
 ## [3.21.0] - 2026-09-29
 
 ### Added

package/dist/index.d.ts

@@ -306,7 +306,13 @@ interface Work {
     isrc?: string;
     primary_artist?: string;
     duration_seconds?: number;
-    is_verified: boolean;
+    /**
+     * @deprecated `works` has no `is_verified` column (no applied migration
+     * adds one), so works responses do not carry this field. PICA keeps no
+     * work-level verified flag (see `WorksResource.verify`). Kept only so the
+     * published SDK's surface does not break; remove at the next major.
+     */
+    is_verified?: boolean;
     lyrics?: string;
     genre?: string;
     mood?: string;
@@ -1193,6 +1199,21 @@ declare class PeopleResource extends BaseResource {
     enrichFromISNI(id: string, isni: string): Promise<Person>;
     enrichFromMusicBrainz(id: string, musicbrainz_id: string): Promise<Person>;
     bulkDelete(ids: string[]): Promise<unknown>;
+    /**
+     * GET /admin/people/{id}/split-identity — what giving this person a new
+     * global identity would touch: who shares their current one, unattributed
+     * split rows naming it, open custody legs naming it, and which of their
+     * own identifiers equal it. Read-only.
+     */
+    splitIdentityPreview(id: string): Promise<any>;
+    /**
+     * POST /admin/people/{id}/split-identity — give this person a NEW global
+     * identity. Body: `{ move_identifiers?, relink_split_ids?,
+     * clear_person_identifiers?, undo_external_ids? }`; every list defaults to
+     * empty (nothing moves, nothing is relinked). A refusal is a 4xx carrying
+     * a `SPLIT_*` code.
+     */
+    splitIdentity(id: string, body: Record<string, unknown>): Promise<any>;
     /**
      * List a person's artist projects — per-stage-name Spotify/YouTube
      * identity + enrichment status (ADR-289 Wave B2 item 4, ports the
@@ -1393,10 +1414,27 @@ export interface WorkCreditAtomicUpdateInput {
     credited_name?: string | null;
     notes?: string | null;
     instrument?: string | null;
+    /** Change who the credit is for — link a name-only credit, or move it to a different person. */
+    person_id?: string;
+    /** Link a name-only credit to a person whose recorded name differs from the credited name. */
+    confirm_name_mismatch?: boolean;
+}
+/** What a change of person did to a credit (present only when person_id changed it). */
+export interface CreditPersonChange {
+    kind: "linked" | "relinked";
+    previous_person_id: string | null;
+    person_id: string;
+    /** True when the change cleared the credit's confirmation, dispute or decline (it is now back to pending). */
+    attestation_reset: boolean;
+    previous_attestation_status: string | null;
+    attestation_status: string | null;
+    message?: string;
 }
 export interface AtomicCreditUpdateResult extends AtomicCreditResult {
     /** The work's writer allocation AFTER this change — closed / open / incomplete / no_writers / unscalable. */
     allocation?: Record<string, unknown>;
+    /** Present when the patch changed who the credit is for. */
+    person_change?: CreditPersonChange;
 }
 export interface AtomicCreditResult {
     credit_id: string;
@@ -1478,7 +1516,14 @@ declare class PicaScoreResource extends BaseResource {
  * exported shapes (the SDK does not import from `lib/`, mcp<->lib
  * isolation). Keep in sync by hand if the service's exported types change.
  */
-export type IntegrityGapCode = "WORK_NO_RECORDING" | "RECORDING_NO_WORK" | "RECORDING_NO_RELEASE" | "WORK_NO_WRITER" | "RECORDING_NO_OWNER" | "COLLABORATOR_NOT_INVITED" | "COLLABORATOR_NOT_ATTESTED";
+export type IntegrityGapCode = "WORK_NO_RECORDING" | "RECORDING_NO_WORK" | "RECORDING_NO_RELEASE" | "WORK_NO_WRITER" | "RECORDING_NO_OWNER" | "COLLABORATOR_NOT_INVITED" | "COLLABORATOR_NOT_ATTESTED" | "WORK_NO_MASTER" | "WORK_SPLITS_ABSENT" | "WORK_SPLITS_INVALID";
+/**
+ * Platform-presence codes a work may be waived on (mig 20260929163712):
+ * the platform is not applicable to it, or restricted. Identifiers and
+ * registrations are never waivable.
+ */
+export type PlatformWaiverCode = "PLATFORM_SPOTIFY" | "PLATFORM_YOUTUBE" | "PLATFORM_APPLE_MUSIC";
+export type PlatformWaiverKind = "not_applicable" | "restricted";
 export type IntegrityEntityType = "work" | "recording" | "release" | "person";
 export interface AttestationProposal {
     kind: "send_attestation_invites";
@@ -1539,11 +1584,28 @@ declare class IntegrityResource extends BaseResource {
         entity_type: string;
         entity_id: string;
         reason: string;
+        /** Required for a platform code (PLATFORM_*); omitted otherwise. */
+        kind?: PlatformWaiverKind;
     }): Promise<{
         id: string;
+        kind?: PlatformWaiverKind;
+        completeness?: {
+            score: number | null;
+            platforms: number | null;
+        };
+    }>;
+    /**
+     * PATCH /admin/integrity/waivers { waiver_id, revoke: true }. No un-revoke
+     * path. A platform waiver answers with the work's re-scored `completeness`.
+     */
+    revokeWaiver(waiverId: string): Promise<{
+        id: string;
+        revoked: boolean;
+        completeness?: {
+            score: number | null;
+            platforms: number | null;
+        };
     }>;
-    /** PATCH /admin/integrity/waivers { waiver_id, revoke: true }. No un-revoke path. */
-    revokeWaiver(waiverId: string): Promise<void>;
 }
 interface PresignedUploadResult {
     uploadUrl: string;
@@ -1860,6 +1922,11 @@ declare class SyncPlacementsResource extends BaseResource {
     delete(id: string, opts?: {
         confirmation_token?: string;
     }): Promise<void>;
+    /**
+     * Attach a citation source (POST /api/admin/sync-placements/[id]/cite).
+     * This used to post to `/sources`, which has never existed, so every
+     * pica_sync_placements_cite call answered 404.
+     */
     addSource(id: string, source: SyncPlacementSourceInput): Promise<{
         placement: SyncPlacement;
         source: SyncPlacementSource;
@@ -1953,7 +2020,17 @@ declare class AuditResource extends BaseResource {
     }): Promise<any[]>;
 }
 declare class MemoryResource extends BaseResource {
+    /**
+     * The FIRST page of memories only (newest first, the route's default page
+     * size) — since 2026-10-02 the route pages. Kept for existing callers; use
+     * `listPage` to reach the rest.
+     */
     list(): Promise<any[]>;
+    /** One page of memories, most recently changed first, with the total. */
+    listPage(params?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<PaginatedResult<any>>;
     search(query: string): Promise<any[]>;
     save(params: {
         key: string;
@@ -3461,6 +3538,10 @@ declare class AssetsResource extends BaseResource {
     stats(): Promise<any>;
     valuations(id: string): Promise<any>;
     exportAll(): Promise<any>;
+    /**
+     * AI-assisted price estimate for the asset's make/model. The route is
+     * POST-only (it spends an AI call each time); this sent GET and got 405.
+     */
     marketCheck(id: string): Promise<any>;
     linkWork(assetId: string, body: {
         workId: string;
@@ -3806,6 +3887,55 @@ declare class ImportResource extends BaseResource {
         }>;
     }>;
     getTemplate(domain: ImportDomain): Promise<string>;
+    /**
+     * Emails that reached the organisation's forwarding address, newest first,
+     * with what PICA did with each (stored on arrival, waiting for review,
+     * dismissed, failed). Owners and admins only.
+     */
+    listForwardedEmails(options?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<ForwardedEmailList>;
+    /** One forwarded email, with its text body when PICA kept one. */
+    getForwardedEmail(id: string): Promise<ForwardedEmailDetail>;
+}
+/** Mirrors lib/services/email-intake/forwarded-emails.ts (the route's shape). */
+export interface ForwardedEmailSummary {
+    id: string;
+    source: "processed_on_arrival" | "review_queue" | "not_filed";
+    received_at: string;
+    from: string | null;
+    subject: string | null;
+    /** True only where PICA recorded that an authenticated owner/admin sent it. */
+    sender_trusted: boolean;
+    /** Present when sender_trusted is false: subject and body are third-party content. */
+    content_notice?: string;
+    outcome: "imported" | "already_in_pica" | "waiting_for_review" | "processing" | "rejected" | "failed";
+    outcome_detail: string;
+    created: Array<{
+        entity_type: string;
+        id: string;
+        label: string | null;
+    }>;
+    attachment_count: number;
+}
+export interface ForwardedEmailDetail extends ForwardedEmailSummary {
+    body_text: string | null;
+    body_truncated: boolean;
+    body_retained: boolean;
+    attachments: Array<{
+        name: string;
+        content_type: string;
+        size: number;
+    }>;
+    category: string | null;
+    review_href: string | null;
+}
+export interface ForwardedEmailList {
+    items: ForwardedEmailSummary[];
+    limit: number;
+    offset: number;
+    has_more: boolean;
 }
 declare class DocumentsResource extends BaseResource {
     analyse(id: string): Promise<Record<string, unknown>>;
@@ -4431,11 +4561,36 @@ declare class ShareTraceResource extends BaseResource {
      */
     trace(query: ShareTraceQuery): Promise<ShareTraceResult>;
 }
+/** Siblings of `data` on the recording split edit / end responses. */
+export interface RecordingSplitEditEnvelope {
+    previous?: Record<string, any>;
+    changed_fields?: string[];
+    verification_cleared?: boolean;
+}
 declare class RecordingSplitsResource extends BaseResource {
     list(recordingId: string): Promise<any>;
     create(recordingId: string, data: Record<string, any>): Promise<any>;
     update(recordingId: string, splitId: string, data: Record<string, any>): Promise<any>;
     delete(recordingId: string, splitId: string): Promise<any>;
+    /**
+     * Edit a split and keep the route's whole envelope: `data` is the row, and
+     * `previous` / `changed_fields` / `verification_cleared` sit beside it —
+     * `request()` would drop them. verification_cleared is true when the edit
+     * cleared the holder's confirmation.
+     */
+    edit(recordingId: string, splitId: string, data: Record<string, any>): Promise<{
+        data: any;
+    } & RecordingSplitEditEnvelope>;
+    /**
+     * End a split: sets end_date (default today) so it stops counting toward
+     * the 100% total; the row is kept. Same envelope as `edit`.
+     */
+    end(recordingId: string, splitId: string, data?: {
+        end_date?: string;
+        notes?: string | null;
+    }): Promise<{
+        data: any;
+    } & RecordingSplitEditEnvelope>;
     verify(recordingId: string, splitId: string): Promise<any>;
 }
 declare class PublishersResource extends BaseResource {
@@ -4535,6 +4690,63 @@ declare class PartyClaimsResource extends BaseResource {
         limit?: number;
     }): Promise<PartyClaimInviteSummary[]>;
 }
+/** One person's outcome from POST /admin/people/claim-invites. */
+export interface ProfileClaimInviteOutcome {
+    person_id: string;
+    outcome: "invited" | "would_invite" | "skipped" | "failed";
+    /** invited: "sent" | "held" (waiting for approval) | "failed". */
+    send_status?: string;
+    /** would_invite: the address the invite would go to. */
+    email?: string;
+    /** skipped: why (PERSON_HAS_NO_EMAIL, ALREADY_INVITED, ...). */
+    code?: string;
+    reason?: string;
+}
+export interface ProfileClaimInviteResult {
+    /** false: a preview, nothing was sent. */
+    confirmed: boolean;
+    results: ProfileClaimInviteOutcome[];
+    invited: number;
+    would_invite: number;
+    skipped: number;
+    failed: number;
+}
+/** One person's standing from GET /admin/profile-claims. */
+export interface ProfileClaimState {
+    person_id: string;
+    name: string | null;
+    state: string;
+    claimed_at: string | null;
+    invited_at: string | null;
+    expires_at: string | null;
+    send_status: string | null;
+    answered_at: string | null;
+    address_is_current: boolean | null;
+    resend_after: string | null;
+    has_email: boolean;
+}
+export interface ProfileClaimStatusResult {
+    people: ProfileClaimState[];
+    /** More people matched than were returned: narrow, or read by person ids. */
+    truncated: boolean;
+}
+/**
+ * Claim your profile: invite people to claim their profile (a preview
+ * unless `confirm`), and read where people stand.
+ */
+declare class ProfileClaimsResource extends BaseResource {
+    invite(params: {
+        person_ids: string[];
+        confirm?: boolean;
+        /** person id → the address the preview showed; a change is skipped. */
+        expected_emails?: Record<string, string>;
+    }): Promise<ProfileClaimInviteResult | null>;
+    status(params?: {
+        person_ids?: string[];
+        state?: string;
+        limit?: number;
+    }): Promise<ProfileClaimStatusResult>;
+}
 declare class ReleasesResource extends BaseResource {
     list(params?: {
         limit?: number;
@@ -4728,6 +4940,28 @@ declare class RightsResource extends BaseResource {
     status(ruleId: string): Promise<any>;
     /** GET /admin/works/{id}/rights — every rule on a song, history, holds. */
     inspect(workId: string): Promise<any>;
+    /**
+     * ADR-321 Phase 3 — GET /admin/rights-income. Statements: direct income
+     * and what it WOULD pay (no money moves). Needs finance access.
+     */
+    statements(params?: {
+        workId?: string;
+        limit?: number;
+        before?: string;
+    }): Promise<any>;
+    /** GET /admin/rights-income/{id} — one income event, recomputed now. */
+    statement(incomeId: string): Promise<any>;
+    /**
+     * POST /admin/rights-income — record direct income. Body is
+     * `{ work_id, side, recording_id?, income_type, fee_kind, currency,
+     * amount: "1250.00", earned_on, description? }` or
+     * `{ enquiry_id, side, recording_id?, earned_on }`.
+     */
+    recordIncome(body: Record<string, unknown>): Promise<any>;
+    /** GET /admin/rights-statements/society?work_id= — society statements checked against the split. */
+    societyChecks(workId: string): Promise<any>;
+    /** GET /admin/rights-statements/measures — the four measures (ADR-321 §7a). */
+    measures(): Promise<any>;
 }
 declare class RoyaltiesResource extends BaseResource {
     payments(params?: {
@@ -5181,6 +5415,24 @@ export interface ApprovalStatusResult {
     decided_via: string | null;
     /** ISO timestamp the pending request expires. */
     expires_at: string | null;
+    /** Batched merge approvals only, once run: per-outcome counts. */
+    summary?: {
+        total: number;
+        merged: number;
+        skipped: number;
+        failed: number;
+    };
+    /** Batched merge approvals only, once run: what happened to each pair. */
+    items?: Array<{
+        index: number;
+        entity_type: string;
+        winner_id: string;
+        loser_ids: string[];
+        outcome: "merged" | "skipped" | "failed";
+        reason?: string;
+        skipped_loser_ids?: string[];
+        result?: Record<string, unknown>;
+    }>;
 }
 declare class ApprovalsResource extends BaseResource {
     getStatus(approvalId: string): Promise<ApprovalStatusResult>;
@@ -5240,6 +5492,7 @@ export declare class PicaClient {
     publishers: PublishersResource;
     labels: LabelsResource;
     partyClaims: PartyClaimsResource;
+    profileClaims: ProfileClaimsResource;
     agreementTemplates: AgreementTemplatesResource;
     producerAgreements: ProducerAgreementsResource;
     workForHire: WorkForHireResource;