@withpica/mcp-sdk 3.22.0 → 3.23.1

package/CHANGELOG.md

@@ -11,6 +11,51 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.23.1] - 2026-10-07
+
+### Fixed
+
+- `imports.getTemplate()` and `catalogStats()` go through the shared request
+  path. Both were bare `fetch()` calls without the
+  `x-vercel-protection-bypass` header, so on a protected Vercel preview they
+  never reached PICA: `getTemplate` returned Vercel's login page as the CSV
+  (or failed when that hop answered 500). They also skipped the timeout,
+  retry and typed errors.
+- `requestText()` refuses a `text/html` body instead of returning it as the
+  file.
+
+## [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
@@ -35,6 +80,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   `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

@@ -943,13 +943,20 @@ declare class BaseResource {
      * for routes that stream a generated file (e.g. `text/csv`) rather than
      * `{success, data}`. `request()` unconditionally calls `response.json()`,
      * which throws a SyntaxError parsing CSV text; every such route needs this
-     * method instead (see `ImportResource.getTemplate()` for the prior
-     * precedent this generalises).
+     * method instead (`ImportResource.getTemplate()`, `ExportResource.catalogCsv()`).
      *
      * `fetchWithRetry` already throws `ApiError` for non-2xx responses (reading
      * the body as text), so reaching here means `response.ok`. Still guard
      * against a 2xx JSON error envelope (`{success:false}`) via content-type,
      * since a route can commit to status 200 before a later validation step.
+     *
+     * An HTML page is refused. Neither route that uses this
+     * (`/admin/import/template`, `/admin/works/export` CSV formats) answers
+     * `text/html`, so one means something in front of PICA answered (on a
+     * protected Vercel preview, a missing bypass header ends on Vercel's
+     * login page with status 200). Returning that page as the file read as a
+     * success (2026-10-06, pica_import_template). Locked by
+     * `mcp-server/src/__tests__/sdk-request-text-and-bare-fetch.test.ts`.
      */
     protected requestText(method: string, path: string): Promise<string>;
     /**
@@ -1199,6 +1206,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
@@ -1399,10 +1421,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;
@@ -1890,6 +1929,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;
@@ -1983,7 +2027,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;
@@ -3491,6 +3545,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;
@@ -3836,6 +3894,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>>;
@@ -4461,11 +4568,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 {
@@ -4565,6 +4697,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;
@@ -5233,6 +5422,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>;
@@ -5292,6 +5499,7 @@ export declare class PicaClient {
     publishers: PublishersResource;
     labels: LabelsResource;
     partyClaims: PartyClaimsResource;
+    profileClaims: ProfileClaimsResource;
     agreementTemplates: AgreementTemplatesResource;
     producerAgreements: ProducerAgreementsResource;
     workForHire: WorkForHireResource;