@withpica/mcp-sdk 1.27.0 → 1.28.0

package/dist/index.js

@@ -258,6 +258,16 @@ class WorksResource extends BaseResource {
         const result = await this.request("GET", `/admin/works/${workId}/releases`);
         return result?.data || [];
     }
+    /**
+     * 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.
+     */
+    async attest(workId, input) {
+        return this.request("POST", `/admin/works/${workId}/attest`, input ?? {});
+    }
 }
 class PeopleResource extends BaseResource {
     async list(params) {
@@ -406,6 +416,16 @@ class CreditsResource extends BaseResource {
     async atomicRemove(workId, creditId) {
         return this.request("DELETE", `/admin/works/${workId}/credits/${creditId}`);
     }
+    /**
+     * 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.
+     */
+    async sendForAttestation(workId, input) {
+        return this.request("POST", `/admin/works/${workId}/credits/send-for-attestation`, input ?? {});
+    }
 }
 class CreditsBalanceResource extends BaseResource {
     async getBalance() {
@@ -1051,6 +1071,22 @@ class DashboardResource extends BaseResource {
     async pulse() {
         return this.request("GET", "/admin/dashboard/pulse");
     }
+    /**
+     * 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.
+     */
+    async actionableItems(params) {
+        const query = new URLSearchParams();
+        if (params?.class)
+            query.set("class", params.class);
+        if (params?.limit)
+            query.set("limit", String(params.limit));
+        const qs = query.toString();
+        return this.request("GET", `/admin/dashboard/actionable-items${qs ? `?${qs}` : ""}`);
+    }
 }
 // --- Integrations Resource ---
 class IntegrationsResource extends BaseResource {
@@ -1542,8 +1578,11 @@ class ExportResource extends BaseResource {
         const query = params?.format ? `?format=${params.format}` : "";
         return this.request("GET", `/admin/works/export${query}`);
     }
-    async songRegistration() {
-        return this.request("GET", "/admin/exports/song-registration");
+    async songRegistration(params) {
+        const qs = params?.iswc_status
+            ? `?iswc_status=${encodeURIComponent(params.iswc_status)}`
+            : "";
+        return this.request("GET", `/admin/exports/song-registration${qs}`);
     }
     async industryReady() {
         return this.request("GET", "/admin/exports/industry-ready");
@@ -1828,6 +1867,181 @@ class CollaboratorsResource extends BaseResource {
         }
         return results;
     }
+    /**
+     * 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.
+     */
+    async previewByCode(code) {
+        return this.request("POST", "/admin/collaborators/preview-by-code", {
+            code,
+        });
+    }
+    /**
+     * 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`.
+     */
+    async acceptByCode(code) {
+        return this.request("POST", "/admin/collaborators/claim-by-code", { code });
+    }
+    /**
+     * 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.
+     */
+    async declineByCode(code, reason) {
+        return this.request("POST", "/admin/collaborators/decline-by-code", {
+            code,
+            ...(reason ? { reason } : {}),
+        });
+    }
+    /**
+     * 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.
+     */
+    async inviteStatus(params) {
+        const qp = new URLSearchParams();
+        if (params.invite_id)
+            qp.set("invite_id", params.invite_id);
+        if (params.work_id)
+            qp.set("work_id", params.work_id);
+        if (params.include_history)
+            qp.set("include_history", "true");
+        return this.request("GET", `/admin/collaborators/invite-status?${qp.toString()}`);
+    }
+    /**
+     * 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.
+     */
+    async proposeCounter(params) {
+        return this.request("POST", "/admin/collaborators/counters/propose", {
+            code: params.code,
+            credit_type: params.credit_type,
+            percentage_split: params.percentage_split,
+            ...(params.message ? { message: params.message } : {}),
+        });
+    }
+    /**
+     * 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).
+     */
+    async acceptCounter(counterId) {
+        return this.request("POST", "/admin/collaborators/counters/accept", {
+            counter_id: counterId,
+        });
+    }
+    /**
+     * ADR-238 — counter-party declines a pending counter. Reverts invite
+     * to pending; the original proposal is implicitly back on the table.
+     */
+    async declineCounter(counterId, reason) {
+        return this.request("POST", "/admin/collaborators/counters/decline", {
+            counter_id: counterId,
+            ...(reason ? { reason } : {}),
+        });
+    }
+    /**
+     * 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).
+     */
+    async counterBack(params) {
+        return this.request("POST", "/admin/collaborators/counters/counter-back", {
+            counter_id: params.counter_id,
+            credit_type: params.credit_type,
+            percentage_split: params.percentage_split,
+            ...(params.message ? { message: params.message } : {}),
+        });
+    }
+    /**
+     * 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.
+     */
+    async revokeInvite(inviteId) {
+        return this.request("POST", `/admin/collaborators/invites/${inviteId}/revoke`);
+    }
+}
+/**
+ * ADR-236 — cross-org credit visibility for the recipient. Returns works
+ * the caller is credited on in OTHER organisations.
+ */
+class CollaborationsResource extends BaseResource {
+    async received(params) {
+        const qp = new URLSearchParams();
+        if (params?.limit !== undefined)
+            qp.set("limit", String(params.limit));
+        if (params?.offset !== undefined)
+            qp.set("offset", String(params.offset));
+        const qs = qp.toString();
+        return this.request("GET", `/admin/collaborations/received${qs ? `?${qs}` : ""}`);
+    }
+}
+/**
+ * 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).
+ */
+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.
+     */
+    async findByHandle(handle) {
+        const res = await this.request("POST", "/admin/users/find-by-handle", { handle });
+        return res.data;
+    }
+    async setHandle(handle) {
+        const res = await this.request("POST", "/admin/users/handle", { handle });
+        return res.data;
+    }
+    async clearHandle() {
+        await this.request("DELETE", "/admin/users/handle");
+    }
+    async getMyProfile() {
+        const res = await this.request("GET", "/admin/users/profile");
+        return res.data;
+    }
+    async setBio(bio) {
+        const res = await this.request("POST", "/admin/users/bio", { bio });
+        return res.data;
+    }
+    async setAvatarUrl(avatarUrl) {
+        const res = await this.request("POST", "/admin/users/avatar", { avatar_url: avatarUrl });
+        return res.data;
+    }
+    /**
+     * 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`.
+     */
+    async importBioFromPerson(params) {
+        const res = await this.request("POST", "/admin/users/import-bio-from-person", params ?? {});
+        return res.data;
+    }
 }
 class DirectoryResource extends BaseResource {
     async getSettings() {
@@ -1911,6 +2125,16 @@ class CountExplainResource extends BaseResource {
         }
         return this.request("GET", `/admin/count-explain?${params.toString()}`);
     }
+    /**
+     * 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.
+     */
+    async taxonomy() {
+        return this.request("GET", "/admin/count-explain");
+    }
 }
 class AudioPipelineStatusResource extends BaseResource {
     /**
@@ -2459,6 +2683,9 @@ export class PicaClient {
     exports;
     duplicates;
     collaborators;
+    collaborations;
+    // ADR-237 — opt-in public handles + bio + avatar (cross-org discovery)
+    users;
     entityContext;
     comparisons;
     send;
@@ -2556,6 +2783,9 @@ export class PicaClient {
         this.exports = new ExportResource(baseUrl, config.apiKey, debug);
         this.duplicates = new DuplicatesResource(baseUrl, config.apiKey, debug);
         this.collaborators = new CollaboratorsResource(baseUrl, config.apiKey, debug);
+        this.collaborations = new CollaborationsResource(baseUrl, config.apiKey, debug);
+        // ADR-237 — opt-in public handles + bio + avatar (cross-org discovery)
+        this.users = new UsersResource(baseUrl, config.apiKey, debug);
         this.entityContext = new EntityContextResource(baseUrl, config.apiKey, debug);
         this.comparisons = new ComparisonsResource(baseUrl, config.apiKey, debug);
         this.send = new SendResource(baseUrl, config.apiKey, debug);