@withpica/mcp-sdk 1.26.0 → 1.27.1

package/CHANGELOG.md

@@ -11,6 +11,62 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.27.1] - 2026-05-16
+
+### Changed
+
+- Brand consistency: "PICA" → "withPICA" in package metadata (description, author).
+
+### Added
+
+- **`OpsIssueExplicitKind` union widened with `"tool_failure"` (PR #457, 2026-05-15).**
+  Sixth member of the explicit-kind enum on `OpsIssuesResource.reportIssue`,
+  alongside `workflow_gap | inconsistent_result | missing_step | data_issue
+  | ux_confusion`. Mirrored by a first-ever CHECK constraint on
+  `ops_issues.kind` (the column was previously free-text in Postgres).
+  Use this kind for SDK / upstream-tool failures the agent decides are
+  worth reporting — the fail-quiet wrappers on `pica_submit_feedback` and
+  `pica_physical_assets_create` are the canonical callers.
+
+## [1.27.0] - 2026-05-13
+
+> Skipped `1.26.0` — that version was claimed by a parallel publish on
+> 2026-05-12T17:40Z before this branch's publish chain ran. Sister of
+> the `1.23.0 → 1.25.0` hop noted in the `feedback_npm_publish_chain_order`
+> memory entry. CHANGELOG content unchanged; only the version number
+> moved.
+
+### Added
+
+- **`ImportResource.analyze/validate/execute` now accept `fileId` as an alternative to `fileContent` (PR #415 + #416, shipped 2026-05-13).**
+  Closes the workflow loop between `pica_upload` / `pica_upload_complete`
+  and the import pipeline. New `ImportFileSource` discriminated union
+  (`{ fileContent } | { fileId }`) enforces XOR at the call site;
+  the route enforces the same at runtime. When `fileId` is provided
+  (a `documents.id` from `pica_upload_complete`), the server fetches
+  bytes from storage via a short-lived signed URL — agents no longer
+  have to materialise CSV content into tool arguments.
+
+## [1.25.1] - 2026-05-13
+
+### Fixed
+
+- **`PicaImportsResource.analyze` return-type aligned to the route's actual wire shape (PR #408, shipped 2026-05-13).**
+  Type was declared `parsed: { headers, rows, totalRows }`; the route
+  has always returned `parsed: { headers, preview, totalRows, delimiter }`.
+  The mismatch let `mcp-server`'s executor compile a `parsed.rows
+.slice(0, 3)` call that exploded at runtime. Renamed `rows` → `preview`
+  and added the missing `delimiter` field on `ParsedCSV`. The SDK's
+  `request<T>()` is a JSON.parse cast with no runtime validation, so
+  unit tests that mocked the old shape gave false confidence — those
+  were also updated in the companion `@withpica/mcp-server@2.52.1` PR.
+
+## [1.25.0] - 2026-05-12
+
+Closes out the Unreleased buffer accumulated since 1.22.0. The
+`lint-changelog` script that lands in the next sister-package bump
+prevents this drift going forward.
+
 ### Added
 
 - **`FilesResource` on `PicaClient` — first-class outbound file delivery (PR #385, shipped 2026-05-12).**

package/dist/index.d.ts

@@ -663,6 +663,35 @@ declare class WorksResource extends BaseResource {
         track_number: number;
         disc_number: number | null;
     }>>;
+    /**
+     * Stamp a human-creation provenance attestation. Complement to the
+     * AI-disclosure side — captures who signed, when, the attestation
+     * method, supporting-evidence flags, and an optional sha256 signature
+     * hash (raw signature is never persisted). Writes to the
+     * `work_licensing.provenance_attestation` jsonb.
+     */
+    attest(workId: string, input?: {
+        method?: "self_declaration" | "collaborator_verified" | "third_party";
+        supporting_evidence?: {
+            session_files?: boolean;
+            stems_available?: boolean;
+            creation_timeline?: boolean;
+            witness_collaborators?: string[];
+        };
+        signature?: string;
+    }): Promise<{
+        work_id: string;
+        attestation: {
+            human_created: boolean;
+            attested_by: string;
+            attested_at: string;
+            attestation_method: string | null;
+            supporting_evidence: Record<string, unknown>;
+            ip_address?: string;
+            signature_hash?: string;
+            certificate_id?: string;
+        } | null;
+    }>;
 }
 declare class PeopleResource extends BaseResource {
     list(params?: {
@@ -739,6 +768,31 @@ declare class CreditsResource extends BaseResource {
      * semantics — never leaks 404 vs 403 via latency).
      */
     atomicRemove(workId: string, creditId: string): Promise<AtomicCreditResult>;
+    /**
+     * Send pending credits on a work to their recipients for attestation.
+     * Lightweight alternative to pica_split_sheet_send — fans out the
+     * notification rails (in-app + telegram + email) without generating
+     * a formal split-sheet document. Recipients click through to
+     * confirm/dispute; this call only sends the prompt.
+     */
+    sendForAttestation(workId: string, input?: {
+        credit_ids?: string[];
+        reminder_type?: "initial" | "reminder";
+    }): Promise<{
+        sent: number;
+        failed: number;
+        results: Array<{
+            person_id: string;
+            person_name?: string;
+            delivered: boolean;
+            reason?: string;
+            channels?: {
+                in_app: boolean;
+                telegram: boolean;
+                email: boolean;
+            };
+        }>;
+    }>;
 }
 declare class CreditsBalanceResource extends BaseResource {
     getBalance(): Promise<any>;
@@ -1624,7 +1678,7 @@ declare class OpsIssuesResource extends BaseResource {
      * audit trigger can't see.
      */
     reportIssue(params: {
-        kind: "workflow_gap" | "inconsistent_result" | "missing_step" | "data_issue" | "ux_confusion";
+        kind: "workflow_gap" | "inconsistent_result" | "missing_step" | "data_issue" | "tool_failure" | "ux_confusion";
         summary: string;
         attempted?: string;
         expected?: string;
@@ -1773,7 +1827,9 @@ declare class ExportResource extends BaseResource {
     catalogCsv(params?: {
         format?: string;
     }): Promise<any>;
-    songRegistration(): Promise<any>;
+    songRegistration(params?: {
+        iswc_status?: "missing" | "present" | "all";
+    }): Promise<any>;
     industryReady(): Promise<any>;
     catalogAssetReport(params: {
         sections: {
@@ -1906,8 +1962,9 @@ type ImportDomain = "works" | "people" | "recordings" | "documents" | "enquiries
 interface ImportAnalysis {
     parsed: {
         headers: string[];
-        rows: Record<string, string>[];
+        preview: Record<string, string>[];
         totalRows: number;
+        delimiter: string;
     };
     analysis: {
         mappings: Record<string, {
@@ -1949,9 +2006,22 @@ interface ImportResult {
     summary: string;
     dryRun: boolean;
 }
+/**
+ * Source of CSV content — exactly one must be provided:
+ *   - `fileContent`: raw CSV as a string (legacy / inline path)
+ *   - `fileId`: a `documents.id` produced by `pica_upload_complete`,
+ *     resolved server-side via short-lived signed URL. Avoids paying
+ *     the tool-arg cost of pasting large CSVs.
+ */
+type ImportFileSource = {
+    fileContent: string;
+    fileId?: never;
+} | {
+    fileContent?: never;
+    fileId: string;
+};
 declare class ImportResource extends BaseResource {
-    analyze(params: {
-        fileContent: string;
+    analyze(params: ImportFileSource & {
         domain: ImportDomain;
     }): Promise<ImportAnalysis>;
     suggestMapping(params: {
@@ -1970,18 +2040,16 @@ declare class ImportResource extends BaseResource {
         missingRequiredFields: string[];
         aiSuggestions: string[];
     }>;
-    validate(params: {
+    validate(params: ImportFileSource & {
         domain: ImportDomain;
-        fileContent: string;
         mapping: Array<{
             csvColumn: string;
             targetField: string;
             transformType?: string;
         }>;
     }): Promise<ImportValidation>;
-    execute(params: {
+    execute(params: ImportFileSource & {
         domain: ImportDomain;
-        fileContent: string;
         mapping: Array<{
             csvColumn: string;
             targetField: string;
@@ -2195,6 +2263,178 @@ declare class CollaboratorsResource extends BaseResource {
         error?: string;
         email: string;
     }>>;
+    /**
+     * ADR-236 — preview an active invite by its one-time claim_code.
+     * Returns the proposed credit shape WITHOUT mutating. The preview is
+     * informational; a subsequent acceptByCode() atomically re-resolves and
+     * may return `invite_terms_changed` if the sender modified the row.
+     */
+    previewByCode(code: string): Promise<{
+        invite_id: string;
+        work_id: string;
+        work_title: string | null;
+        credit_type: string;
+        percentage_split: number | null;
+        inviter_display_name: string | null;
+        inviter_org_id: string | null;
+        expires_at: string;
+        claim_code: string | null;
+    }>;
+    /**
+     * ADR-236 — accept an invite by its one-time claim_code. Atomically
+     * re-resolves, writes the work_credit row in the inviter's org scope,
+     * flips status to `confirmed`, and invalidates both invite_token and
+     * claim_code. Throws on `invite_no_longer_valid`, `not_recipient`,
+     * `invalid_code`.
+     */
+    acceptByCode(code: string): Promise<Record<string, unknown>>;
+    /**
+     * ADR-236 — recipient declines an invite by claim_code. Optional reason,
+     * max 500 chars. Emits a discovery event to the inviter's org so the
+     * sender's agent surfaces the decline.
+     */
+    declineByCode(code: string, reason?: string): Promise<Record<string, unknown>>;
+    /**
+     * ADR-236 — sender-side invite-status check. Returns status, claim
+     * attempts, recipient resolution, and confirmed_user_id (if claimed).
+     * One of invite_id or work_id is required.
+     *
+     * ADR-238 — `include_history: true` extends the response with `counters:
+     * CollaborationInviteCounter[]` ordered chronologically. The counter
+     * chain is the auditable negotiation trail.
+     */
+    inviteStatus(params: {
+        invite_id?: string;
+        work_id?: string;
+        include_history?: boolean;
+    }): Promise<Record<string, unknown>>;
+    /**
+     * ADR-238 — recipient proposes a counter on an active invite by code.
+     * Server validates the recipient identity (workspace_email match),
+     * round cap (5 per invite across both directions), and supersedes any
+     * prior pending counter. Inserts a new pending counter; flips invite
+     * to counter_proposed; emits counter_proposed event to sender.
+     */
+    proposeCounter(params: {
+        code: string;
+        credit_type: string;
+        percentage_split: number;
+        message?: string;
+    }): Promise<Record<string, unknown>>;
+    /**
+     * ADR-238 — counter-party accepts a pending counter. Atomically writes
+     * work_collaborators with COUNTER's values, flips counter to accepted,
+     * supersedes earlier counters, flips invite to confirmed.
+     * confirmed_user_id is the original recipient regardless of which
+     * party proposed the accepted counter (credit-bearer invariant).
+     */
+    acceptCounter(counterId: string): Promise<Record<string, unknown>>;
+    /**
+     * ADR-238 — counter-party declines a pending counter. Reverts invite
+     * to pending; the original proposal is implicitly back on the table.
+     */
+    declineCounter(counterId: string, reason?: string): Promise<Record<string, unknown>>;
+    /**
+     * ADR-238 — sender counters-back against a recipient's pending or
+     * declined counter. Supersedes prior pending counters; inserts a new
+     * sender-proposed pending counter; invite stays counter_proposed.
+     * Round-cap counts (5 across both directions).
+     */
+    counterBack(params: {
+        counter_id: string;
+        credit_type: string;
+        percentage_split: number;
+        message?: string;
+    }): Promise<Record<string, unknown>>;
+    /**
+     * ADR-236 — sender revokes a pending invite. Destructive tier — the
+     * MCP layer enforces the two-step confirmation_token gate via
+     * @withpica/mcp-utils; the SDK call assumes confirmation has already
+     * been validated.
+     */
+    revokeInvite(inviteId: string): Promise<Record<string, unknown>>;
+}
+/**
+ * ADR-236 — cross-org credit visibility for the recipient. Returns works
+ * the caller is credited on in OTHER organisations.
+ */
+declare class CollaborationsResource extends BaseResource {
+    received(params?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<{
+        works: Array<{
+            work_id: string;
+            title: string;
+            owner_org_id: string;
+            owner_org_name: string;
+            my_role: string;
+            my_split_percentage: number | null;
+            accepted_at: string | null;
+            collaboration_invite_id: string | null;
+        }>;
+        total: number;
+    }>;
+}
+/**
+ * ADR-237 — opt-in public handles + user-authored bio + avatar.
+ * Cross-org discovery surface that lets the sender's agent invite a
+ * collaborator by `@handle` without ever learning the recipient's
+ * email (resolution happens server-side).
+ */
+declare class UsersResource extends BaseResource {
+    /**
+     * Exact-match handle lookup. Same `{ found: false }` shape for
+     * unclaimed | nonexistent | non-string input — never reveals
+     * "exists but private". On a match, the public profile includes
+     * `handle_accepts_invites` so the caller can decide whether to
+     * proceed with an invite.
+     */
+    findByHandle(handle: string): Promise<{
+        found: true;
+        profile: {
+            handle: string;
+            display_name: string | null;
+            avatar_url: string | null;
+            bio: string | null;
+            handle_accepts_invites: boolean;
+        };
+    } | {
+        found: false;
+    }>;
+    setHandle(handle: string): Promise<{
+        handle: string;
+    }>;
+    clearHandle(): Promise<void>;
+    getMyProfile(): Promise<{
+        user_id: string;
+        workspace_email: string | null;
+        full_name: string | null;
+        public_handle: string | null;
+        handle_accepts_invites: boolean;
+        avatar_url: string | null;
+        bio: string | null;
+        linked_person_id: string | null;
+    }>;
+    setBio(bio: string | null): Promise<{
+        bio: string | null;
+    }>;
+    setAvatarUrl(avatarUrl: string | null): Promise<{
+        avatar_url: string | null;
+    }>;
+    /**
+     * Copy `people.biography` into `user_profiles.bio`. Returns the new
+     * bio on success. On `would_overwrite` (existing bio + overwrite
+     * false), surfaces both the existing and proposed bios so the agent
+     * can present a yes/no to the user before re-calling with
+     * `overwrite: true`.
+     */
+    importBioFromPerson(params?: {
+        overwrite?: boolean;
+    }): Promise<{
+        ok?: true;
+        bio?: string;
+    }>;
 }
 interface DirectorySettings {
     organisation_id: string;
@@ -2801,6 +3041,8 @@ export declare class PicaClient {
     exports: ExportResource;
     duplicates: DuplicatesResource;
     collaborators: CollaboratorsResource;
+    collaborations: CollaborationsResource;
+    users: UsersResource;
     entityContext: EntityContextResource;
     comparisons: ComparisonsResource;
     send: SendResource;