@withpica/mcp-sdk 1.27.0 → 1.28.0

package/CHANGELOG.md

@@ -11,6 +11,40 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.28.0] - 2026-05-18
+
+> Skipped `1.27.1` — that version was a brand-consistency-only publish
+> (description/author fields, no source change) shipped via a parallel
+> branch and never made it into this CHANGELOG. Sister of the
+> `1.23.0 → 1.25.0` and `1.25.0 → 1.27.0` hops noted in the
+> `feedback_npm_publish_chain_order` memory entry.
+
+### Added
+
+- **`DashboardResource.actionableItems({ class?, limit? })` (ADR-242, PR #477, 2026-05-18).**
+  Backed by `GET /admin/dashboard/actionable-items` — returns per-row shape
+  `{class, entity_id, entity_type, entity_label, suggested_skill, urgency_score}`
+  sorted by `urgency_score` desc, capped at `limit` (default 20). Drawn from
+  the shared `getActionableIssues()` source of truth, so values agree with
+  `pica_dashboard_briefing.critical_issues_total` and
+  `pica_count_explain.sources[].count` for the same org/moment.
+- **`CountExplainResource.taxonomy()` (ADR-242, PR #477, 2026-05-18).**
+  Backed by `GET /admin/count-explain` (no `count_source`) — returns the
+  full actionable taxonomy as `sources[]` with `drill_down_skill` named
+  per class. Machine-readable routing table for ADR-241's `first-session`
+  skill — reads `count_explain.sources[].drill_down_skill` to pick the next step.
+- **`ActionableTaxonomySource` + `ActionableTaxonomyResult` types** —
+  `{ name, count, drill_down_skill }` row shape + envelope `{ sources, critical_issues_total }`.
+- **`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. Backlogged
+  from the `[Unreleased]` block on develop; shipped in this publish.
+
 ## [1.27.0] - 2026-05-13
 
 > Skipped `1.26.0` — that version was claimed by a parallel publish on

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>;
@@ -1235,6 +1289,17 @@ declare class DashboardResource extends BaseResource {
     }): Promise<any>;
     briefing(): Promise<any>;
     pulse(): Promise<any>;
+    /**
+     * ADR-242 — actionable items projection.
+     * Calls /admin/dashboard/actionable-items which is backed by the
+     * shared getActionableIssues() source of truth. Returns per-row shape
+     * with {class, entity_id, entity_type, entity_label, suggested_skill,
+     * urgency_score}, sorted by urgency_score desc, capped at limit.
+     */
+    actionableItems(params?: {
+        class?: string;
+        limit?: number;
+    }): Promise<any>;
 }
 declare class IntegrationsResource extends BaseResource {
     oauthConnections(): Promise<any>;
@@ -1624,7 +1689,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 +1838,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: {
@@ -2207,6 +2274,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;
@@ -2340,6 +2579,15 @@ export interface CountExplainResult {
         sample_ids: string[];
     }>;
 }
+export interface ActionableTaxonomySource {
+    name: string;
+    count: number;
+    drill_down_skill: string | null;
+}
+export interface ActionableTaxonomyResult {
+    sources: ActionableTaxonomySource[];
+    critical_issues_total: number;
+}
 declare class CountExplainResource extends BaseResource {
     /**
      * GET /admin/count-explain — explains a single dashboard / briefing
@@ -2347,6 +2595,14 @@ declare class CountExplainResource extends BaseResource {
      * down the delta against an observed value.
      */
     explain(query: CountExplainQuery): Promise<CountExplainResult>;
+    /**
+     * ADR-242 — GET /admin/count-explain (no count_source)
+     *
+     * Returns the full actionable taxonomy as sources[] with drill_down_skill.
+     * This is the coherence surface that ties pica_dashboard_briefing.critical_issues_total
+     * to the per-class breakdown, making pica_count_explain a machine-readable routing table.
+     */
+    taxonomy(): Promise<ActionableTaxonomyResult>;
 }
 export interface AudioPipelineStatusQuery {
     window_days?: number;
@@ -2813,6 +3069,8 @@ export declare class PicaClient {
     exports: ExportResource;
     duplicates: DuplicatesResource;
     collaborators: CollaboratorsResource;
+    collaborations: CollaborationsResource;
+    users: UsersResource;
     entityContext: EntityContextResource;
     comparisons: ComparisonsResource;
     send: SendResource;