@withpica/mcp-sdk 3.4.0 → 3.6.0

package/CHANGELOG.md

@@ -11,6 +11,37 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.6.0] - 2026-07-09
+
+### Added
+
+- `SocietyAffiliation` gains `affiliation_kind?: "member" | "origin"` and
+  `Person` gains `origin_countries?: string[]` (ADR-292), mirroring the same
+  fields on the `pica_people_create` / `pica_people_update` write surface.
+
+- **`IntegrityResource`** (`client.integrity`) — the SDK surface for the
+  registration integrity floor (PR #1595): `assessEntity` (work/recording/
+  release grains; release is a documented v1 no-op), `assessOrg`, and the
+  `waive` / `revokeWaiver` write pair backing `pica_integrity_waive`.
+
+- **`requestWithEnvelope()`** on `BaseResource` — like `request()` but
+  returns the FULL parsed `{data, twin?, twin_error?}` envelope instead of
+  narrowing to `.data`. `WorksResource.create` / `RecordingsResource.create`
+  now use it, so the auto-twin routes' `twin`/`twin_error` sibling fields
+  reach callers — `Work`/`Recording` create responses carry `twin` and
+  `twin_error` merged onto the returned entity (commit 689298e3c).
+
+## [3.5.0] - 2026-07-07
+
+### Added
+
+- `catalogStats()` accepts an optional `{ entity, group_by }` argument and
+  serialises it to the query string, powering the Oracle aggregation on
+  `pica_catalog_stats` (one-dimension breakdowns + entity totals). Overloaded so
+  a no-arg call still returns the precise `CatalogStats` envelope type; a call
+  with params returns the widened breakdown shape. Backward-compatible — the
+  no-arg request is byte-identical to before.
+
 ## [3.4.0] - 2026-07-06
 
 ### Changed

package/dist/index.d.ts

@@ -277,6 +277,8 @@ export interface SocietyRegistration {
 export interface SocietyAffiliation {
     society_code: string;
     membership_number: string | null;
+    /** ADR-292: `member` (current, default) or `origin` (home-country society for that code). */
+    affiliation_kind?: "member" | "origin";
 }
 interface Work {
     id: string;
@@ -314,6 +316,11 @@ interface Work {
     licensing_notes?: string | null;
     created_at: string;
     updated_at: string;
+    twin?: {
+        id: string;
+        recording_title: string;
+    } | null;
+    twin_error?: string;
 }
 interface Person {
     id: string;
@@ -331,6 +338,8 @@ interface Person {
     outreach_state?: "ready" | "needs_email" | "needs_disambiguation" | "not_a_target" | "do_not_contact" | "previously_declined";
     /** Society affiliations (ADR-282: society-agnostic write shape). */
     society_affiliations?: SocietyAffiliation[];
+    /** ADR-292: heritage/origin countries (ISO 3166-1 alpha-2, text[] column on public.people). */
+    origin_countries?: string[];
     created_at: string;
     updated_at: string;
 }
@@ -344,6 +353,11 @@ interface Recording {
     society_registrations?: SocietyRegistration[];
     created_at: string;
     updated_at: string;
+    twin?: {
+        id: string;
+        title: string;
+    } | null;
+    twin_error?: string;
 }
 interface ProductionAssetLink {
     asset_id: string;
@@ -807,6 +821,19 @@ declare class BaseResource {
     private fetchWithTimeout;
     private fetchWithRetry;
     protected request<T>(method: string, path: string, body?: any): Promise<T>;
+    /**
+     * Like `request`, but returns the FULL parsed envelope instead of
+     * narrowing to `.data`. Needed by the two spreadsheet-moment auto-twin
+     * routes (`POST /admin/works`, `POST /admin/recordings`), whose response
+     * carries `twin`/`twin_error` as siblings of `data` — `request()`'s
+     * `return data.data || data` would otherwise silently drop them before
+     * the MCP tool ever sees a twin was created.
+     */
+    protected requestWithEnvelope<T>(method: string, path: string, body?: any): Promise<{
+        data: T;
+        twin?: unknown;
+        twin_error?: string;
+    }>;
     /**
      * Make a request whose SUCCESS body is raw text, not a JSON envelope —
      * for routes that stream a generated file (e.g. `text/csv`) rather than
@@ -854,9 +881,45 @@ declare class WorksResource extends BaseResource {
         sort?: "completeness_score:asc" | "completeness_score:desc" | "missing_field_count:asc" | "missing_field_count:desc" | "streaming_activity:asc" | "streaming_activity:desc";
         /** Filter to works registered with a collection society (case-insensitive code, e.g. 'ASCAP', 'PRS', 'GEMA'). */
         society_code?: string;
+        /** Filter by work type (song, instrumental, library, demo, sample). */
+        work_type?: string;
+        /** Filter by work status (demo, unreleased, released, pitched, placed, archived). */
+        work_status?: string;
+        /** Filter to works tagged with this genre (case-sensitive array-contains). */
+        genre?: string;
+        /** Filter to works whose primary recording carries this mood tag. */
+        mood?: string;
+        /** Filter to works whose primary recording tempo is >= this BPM. */
+        tempo_min?: number;
+        /** Filter to works whose primary recording tempo is <= this BPM. */
+        tempo_max?: number;
+        /** Exact primary-artist name match. */
+        primary_artist?: string;
+        /** Exact primary-artist name match (alias of primary_artist). */
+        artist?: string;
+        /** Filter by derived label (primary recording label, else primary release parent_label). */
+        label?: string;
+        /** Filter to works available (true) / not available (false) for licensing. */
+        available_for_licensing?: boolean;
+        /** Filter by the primary release's format (single, ep, album, compilation). */
+        release_format?: string;
+        /** Filter to featured (true) / non-featured (false) works. */
+        is_featured?: boolean;
+        /** Filter by directory-published state. */
+        published?: boolean;
+        /** Only works added/composed on or after this ISO date (YYYY-MM-DD). */
+        created_from?: string;
+        /** Only works added/composed on or before this ISO date (YYYY-MM-DD). */
+        created_to?: string;
+        /** Filter to works that have (true) or lack (false) an ISWC. */
+        has_iswc?: boolean;
+        /** Filter to works that have (true) or lack (false) a publisher_name. */
+        has_publisher?: boolean;
     }): Promise<PaginatedResult<Work>>;
     get(id: string): Promise<Work>;
-    create(data: Partial<Work>): Promise<Work>;
+    create(data: Partial<Work> & {
+        create_twin?: boolean;
+    }): Promise<Work>;
     update(id: string, updates: Partial<Work>): Promise<Work>;
     delete(id: string): Promise<DeletionResult>;
     verify(id: string): Promise<Work>;
@@ -960,6 +1023,14 @@ declare class PeopleResource extends BaseResource {
         record_kind?: "individual" | "placeholder" | "artefact";
         /** Filter by outreach readiness. */
         outreach_state?: "ready" | "needs_email" | "needs_disambiguation" | "not_a_target" | "do_not_contact" | "previously_declined";
+        /** Filter to people who have (true) / lack (false) an email address. */
+        has_email?: boolean;
+        /** Filter to people who have (true) / lack (false) a phone number. */
+        has_phone?: boolean;
+        /** Filter to people holding ANY of these roles (array-overlap). */
+        roles?: string[];
+        /** Filter to people carrying ANY of these tags (array-overlap). */
+        tags?: string[];
     }): Promise<PaginatedResult<Person>>;
     get(id: string): Promise<Person>;
     create(data: Partial<Person>): Promise<Person>;
@@ -1135,6 +1206,79 @@ declare class CreditsBalanceResource extends BaseResource {
 declare class PicaScoreResource extends BaseResource {
     get(): Promise<PicaScore>;
 }
+/**
+ * Registration Integrity Floor (spec 2026-07-09, Task 8). SDK-local types —
+ * duplicated field-for-field from `lib/services/integrity-floor.ts`'s
+ * 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 IntegrityEntityType = "work" | "recording" | "release" | "person";
+export interface AttestationProposal {
+    kind: "send_attestation_invites";
+    people: Array<{
+        person_id: string;
+        name: string;
+        has_email: boolean;
+    }>;
+    tool: "pica_collaborators_invite_bulk";
+    note: string;
+}
+export interface IntegrityGap {
+    code: IntegrityGapCode;
+    entity: {
+        type: IntegrityEntityType;
+        id: string;
+        label: string;
+    };
+    severity: "critical" | "important";
+    label: string;
+    action_hint: string;
+    proposed_action?: AttestationProposal;
+    waivable: true;
+}
+export interface EntityAssessment {
+    entity: {
+        type: IntegrityEntityType;
+        id: string;
+    };
+    gaps: IntegrityGap[];
+    waived_count: number;
+}
+export interface OrgIntegritySummary {
+    total_gaps: number;
+    critical_gaps: number;
+    waived_gaps: number;
+    top_gaps: IntegrityGap[];
+    attestation_pending: number;
+    is_empty_catalog: boolean;
+}
+declare class IntegrityResource extends BaseResource {
+    /**
+     * GET /admin/integrity/assess?entity_type=&entity_id= -> single-entity assessment.
+     * NOTE: for entity_type "release" this is a documented v1 no-op — no
+     * release-grain gap code exists yet, so `gaps` is always empty by design
+     * (see assessEntity's release branch in lib/services/integrity-floor.ts).
+     */
+    assessEntity(entityType: "work" | "recording" | "release", entityId: string): Promise<EntityAssessment>;
+    /** GET /admin/integrity/assess (no params) -> org-grain summary. */
+    assessOrg(): Promise<OrgIntegritySummary>;
+    /**
+     * POST /admin/integrity/waivers. Duplicate-active-waiver is a 409
+     * (`ConflictError` on the app side) — surfaces here as a non-retryable
+     * `ApiError` with `status === 409` (see `BaseResource.request`).
+     */
+    waive(input: {
+        gap_code: string;
+        entity_type: string;
+        entity_id: string;
+        reason: string;
+    }): Promise<{
+        id: string;
+    }>;
+    /** PATCH /admin/integrity/waivers { waiver_id, revoke: true }. No un-revoke path. */
+    revokeWaiver(waiverId: string): Promise<void>;
+}
 interface PresignedUploadResult {
     uploadUrl: string;
     uploadId: string;
@@ -1273,6 +1417,18 @@ declare class AgreementsResource extends BaseResource {
          * the hood.
          */
         awaiting_signature?: boolean;
+        /** Agreements with start_date on/after this ISO date (YYYY-MM-DD). */
+        start_date_from?: string;
+        /** Agreements with start_date on/before this ISO date. */
+        start_date_to?: string;
+        /** Agreements with end_date on/after this ISO date. */
+        end_date_from?: string;
+        /** Agreements with end_date on/before this ISO date. */
+        end_date_to?: string;
+        /** Active agreements whose end_date falls within N days from today. */
+        expiring_within_days?: number;
+        /** true → only agreements that have an end_date; false → only open-ended. */
+        has_end_date?: boolean;
         limit?: number;
         offset?: number;
     }): Promise<Agreement[]>;
@@ -1496,9 +1652,23 @@ declare class RecordingsResource extends BaseResource {
         missing_field_count_gt?: number;
         /** ADR-270 §3.4 — filter: missing_field_count strictly less than this */
         missing_field_count_lt?: number;
+        /** Structured Recall — filter to recordings with (true) or without (false) an ISRC */
+        has_isrc?: boolean;
+        /** Structured Recall — filter by version type */
+        version_type?: string;
+        /** Structured Recall — inclusive ISO date range on recordings.recorded_at */
+        recorded_from?: string;
+        /** Structured Recall — inclusive ISO date range on recordings.recorded_at */
+        recorded_to?: string;
+        /** Structured Recall — inclusive ISO date range on recordings.created_at */
+        created_from?: string;
+        /** Structured Recall — inclusive ISO date range on recordings.created_at */
+        created_to?: string;
     }): Promise<PaginatedResult<Recording>>;
     get(id: string): Promise<Recording>;
-    create(data: Partial<Recording>): Promise<Recording>;
+    create(data: Partial<Recording> & {
+        create_twin?: boolean;
+    }): Promise<Recording>;
     update(id: string, updates: Partial<Recording>): Promise<Recording>;
     delete(id: string): Promise<DeletionResult>;
     getByWork(workId: string): Promise<Recording[]>;
@@ -3652,6 +3822,8 @@ declare class ReleasesResource extends BaseResource {
         query?: string;
         upc?: string;
         spotify_album_id?: string;
+        release_date_from?: string;
+        release_date_to?: string;
     }): Promise<any>;
     get(id: string): Promise<any>;
     /**
@@ -4207,10 +4379,15 @@ export declare class PicaClient {
     shareSend: ShareSendResource;
     accessSimulate: AccessSimulateResource;
     approvals: ApprovalsResource;
+    integrity: IntegrityResource;
     /**
      * Get accurate catalog stats via SQL counts (no pagination limits)
      */
     catalogStats(): Promise<CatalogStats>;
+    catalogStats(params: {
+        entity?: string;
+        group_by?: string;
+    }): Promise<CatalogStats | Record<string, unknown>>;
     constructor(config: PicaClientConfig);
 }
 export type { Work, Person, Recording, PaginatedResult, PicaClientConfig, SyncSearchParams, SyncTrack, SyncSearchResult, LicenseEnquiryInput, LicenseEnquiry, BookingEnquiry, WorkCredit, WorkCreditsInput, PicaScore, PicaScorePillar, AudioFile, AudioAnalysisStatus, PresignedUploadResult, CompleteUploadResult, IdentifyResult, MultimediaItem, Agreement, AgreementWorkLink, CreateAgreementFromTemplateParams, AgreementSendForSignatureResult, AgreementSendForSignatureSentEntry, AgreementSendForSignatureSkippedEntry, AgreementSendForSignatureSkipReason, SyncPlacement, SyncPlacementSource, SyncPlacementRecording, SyncPlacementWithRelations, SyncPlacementContactInput, SyncPlacementRecordingInput, SyncPlacementSourceInput, CreateSyncPlacementInput, UpdateSyncPlacementInput, SyncPlacementQueryParams, SyncPlacementStatus, SyncPlacementVerificationStatus, SyncPlacementConfidentialityLevel, SyncPlacementSourceKind, CatalogStats, NotificationsSummary, CreateUploadSessionInput, CreateUploadSessionResult, };