@withpica/mcp-sdk 3.5.0 → 3.7.0

package/CHANGELOG.md

@@ -11,6 +11,38 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.7.0] - 2026-07-12
+
+### Added
+
+- **`WorksResource.dossier(workId)`** — fetches the full song dossier for one
+  work (`GET /admin/works/[id]/dossier?format=json`): work, recordings,
+  releases, composition credits, people, provenance, AI disclosure, and
+  consent, assembled server-side by `assembleSongDossier`. Backs the new
+  `dossier` section of `pica_works_inspect`. JSON only in the SDK; the PDF
+  export stays on the web UI. `request()` unwraps the `{ success, data }`
+  envelope to the dossier itself.
+
+## [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

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
@@ -890,7 +917,9 @@ declare class WorksResource extends BaseResource {
         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>;
@@ -912,6 +941,50 @@ declare class WorksResource extends BaseResource {
         track_number: number;
         disc_number: number | null;
     }>>;
+    /**
+     * Assemble the full song dossier for one work — everything PICA holds about
+     * a song in one call (work, recordings, releases, composition credits,
+     * people, provenance, AI disclosure, consent). Backs the `dossier` section
+     * of pica_works_inspect. JSON format only here; the PDF export lives on the
+     * web UI (`GET /admin/works/[id]/dossier?format=pdf`).
+     *
+     * `request()` unwraps the `{ success, data }` envelope to the dossier itself.
+     */
+    dossier(workId: string): Promise<{
+        schemaVersion: number;
+        generatedAt: string;
+        work: {
+            id: string;
+            title: string;
+            workType: string | null;
+            status: string | null;
+            iswc: string | null;
+            completenessScore: number | null;
+            [k: string]: unknown;
+        };
+        recordings: unknown[];
+        releases: unknown[];
+        compositionCredits: unknown[];
+        people: unknown[];
+        provenance: {
+            attestationStatus: string | null;
+            hasProvenanceCertificate: boolean;
+            certificateId: string | null;
+            [k: string]: unknown;
+        };
+        aiDisclosure: {
+            disclosed: boolean;
+            [k: string]: unknown;
+        };
+        consent: {
+            workEffective: {
+                state: string;
+                level?: string;
+            };
+            [k: string]: unknown;
+        };
+        [k: string]: unknown;
+    }>;
     /**
      * Stamp a human-creation provenance attestation. Complement to the
      * AI-disclosure side — captures who signed, when, the attestation
@@ -1177,6 +1250,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;
@@ -1564,7 +1710,9 @@ declare class RecordingsResource extends BaseResource {
         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[]>;
@@ -4275,6 +4423,7 @@ export declare class PicaClient {
     shareSend: ShareSendResource;
     accessSimulate: AccessSimulateResource;
     approvals: ApprovalsResource;
+    integrity: IntegrityResource;
     /**
      * Get accurate catalog stats via SQL counts (no pagination limits)
      */