@withpica/mcp-sdk 3.1.1 → 3.3.0

package/dist/index.js

@@ -203,6 +203,43 @@ class BaseResource {
         }
         return (data.data || data);
     }
+    /**
+     * 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
+     * `{success, data}`. `request()` unconditionally calls `response.json()`,
+     * which throws a SyntaxError parsing CSV text; every such route needs this
+     * method instead (see `ImportResource.getTemplate()` for the prior
+     * precedent this generalises).
+     *
+     * `fetchWithRetry` already throws `ApiError` for non-2xx responses (reading
+     * the body as text), so reaching here means `response.ok`. Still guard
+     * against a 2xx JSON error envelope (`{success:false}`) via content-type,
+     * since a route can commit to status 200 before a later validation step.
+     */
+    async requestText(method, path) {
+        const url = `${this.baseUrl}${path}`;
+        const timeoutMs = getTimeoutForPath(path);
+        if (this.debug) {
+            console.error(`[PICA SDK] ${method} ${url} (timeout: ${timeoutMs}ms)`);
+        }
+        const response = await this.fetchWithRetry(url, {
+            method,
+            headers: {
+                Authorization: `Bearer ${this.apiKey}`,
+                ...this.getBypassHeaders(),
+            },
+        }, timeoutMs);
+        const contentType = response.headers.get("content-type") || "";
+        if (contentType.includes("application/json")) {
+            const data = await response.json();
+            if (data && typeof data === "object" && data.success === false) {
+                const msg = typeof data.error === "string" ? data.error : "unspecified error";
+                throw new ApiError(`API returned success:false: ${msg}`, response.status, false);
+            }
+            return typeof data === "string" ? data : JSON.stringify(data);
+        }
+        return response.text();
+    }
     /**
      * Make a request and return paginated result with metadata
      */
@@ -393,6 +430,45 @@ class PeopleResource extends BaseResource {
     async bulkDelete(ids) {
         return this.request("POST", "/admin/people/bulk-delete", { ids });
     }
+    /**
+     * List a person's artist projects — per-stage-name Spotify/YouTube
+     * identity + enrichment status (ADR-289 Wave B2 item 4, ports the
+     * bespoke assistant's `get_person_artist_projects`).
+     */
+    async listArtistProjects(personId) {
+        return this.request("GET", `/admin/people/${personId}/artist-projects`);
+    }
+    /**
+     * Trigger enrichment for every stage name on a person — matches each
+     * against Spotify/YouTube artist identity, auto-applying confident
+     * matches and flagging ambiguous ones for disambiguation (ADR-289
+     * Wave B2 item 4, ports `enrich_artist_projects`).
+     */
+    async enrichArtistProjects(personId) {
+        return this.request("POST", `/admin/people/${personId}/enrich-artist-projects`);
+    }
+    /**
+     * Mark one of a person's artist projects as primary (unsets any other
+     * primary project for the same person server-side) (ADR-289 Wave B2
+     * item 4, ports `set_primary_artist_project`).
+     */
+    async setPrimaryArtistProject(artistProjectId) {
+        return this.request("PATCH", `/admin/artist-projects/${artistProjectId}/set-primary`);
+    }
+    /**
+     * Check whether an external artist name already matches an existing
+     * person — exact MusicBrainz-id match, then ISNI-via-MusicBrainz, then
+     * a fuzzy name fallback. Read-only (ADR-289 Wave B2 item 5, ports the
+     * bespoke assistant's `triangulate_artist` — verdict: NOT subsumed by
+     * `pica_resolve_person`, which requires an existing person_id and
+     * writes identifiers rather than searching for a match by bare name).
+     */
+    async triangulate(params) {
+        const qp = new URLSearchParams({ artist_name: params.artist_name });
+        if (params.musicbrainz_id)
+            qp.set("musicbrainz_id", params.musicbrainz_id);
+        return this.request("GET", `/admin/people/triangulate?${qp.toString()}`);
+    }
 }
 class LicensingResource extends BaseResource {
     /**
@@ -478,6 +554,58 @@ class LicensingResource extends BaseResource {
     async updateEnquiryStatus(id, status, notes) {
         return this.request("PATCH", `/admin/license-enquiries/${id}`, { status, your_notes: notes });
     }
+    /**
+     * Set a counter offer on a license enquiry (ADR-289 Wave B1 item 6 —
+     * counter-offer fields on `pica_update_license_enquiry_status`, ports
+     * the bespoke assistant's `set_license_counter_offer`). Setting a counter
+     * offer also moves the enquiry to status "quoted" server-side.
+     */
+    async setLicenseEnquiryCounterOffer(id, counterOffer, notes) {
+        return this.request("PATCH", `/admin/license-enquiries/${id}`, { counterOffer, notes });
+    }
+}
+/**
+ * ADR-289 Wave C1 — booking enquiries (internal-team session/production
+ * bookings, distinct from `LicensingResource`'s sync-license enquiries).
+ * Wraps `/admin/bookings` + `/admin/bookings/[id]`.
+ */
+class BookingsResource extends BaseResource {
+    /**
+     * List/search booking enquiries. `GET /admin/bookings` returns the raw
+     * array (not `{data, count}`) — `request()` unwraps to that array.
+     */
+    async list(params) {
+        const qp = new URLSearchParams();
+        if (params?.status)
+            qp.set("status", params.status);
+        if (params?.priority)
+            qp.set("priority", params.priority);
+        if (params?.query)
+            qp.set("query", params.query);
+        if (params?.enquiry_type)
+            qp.set("enquiry_type", params.enquiry_type);
+        if (params?.follow_up_required !== undefined)
+            qp.set("follow_up_required", String(params.follow_up_required));
+        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/bookings${qs ? `?${qs}` : ""}`);
+    }
+    async get(id) {
+        return this.request("GET", `/admin/bookings/${encodeURIComponent(id)}`);
+    }
+    /**
+     * `PATCH /admin/bookings/[id]` only processes ONE update mode per call
+     * (status, OR responseContent+respondedBy, OR followUp — the route
+     * returns on the first matching branch). Callers needing multiple
+     * independent updates in one tool invocation must call this once per
+     * mode (mirrors the bespoke assistant's three separate handlers).
+     */
+    async update(id, data) {
+        return this.request("PATCH", `/admin/bookings/${encodeURIComponent(id)}`, data);
+    }
 }
 class CreditsResource extends BaseResource {
     async listForWork(workId) {
@@ -636,6 +764,8 @@ class AgreementsResource extends BaseResource {
             queryParams.set("party_name", params.party_name);
         if (params?.includeWorkCounts)
             queryParams.set("includeWorkCounts", "true");
+        if (params?.awaiting_signature)
+            queryParams.set("awaiting_signature", "true");
         if (params?.limit !== undefined)
             queryParams.set("limit", String(params.limit));
         if (params?.offset !== undefined)
@@ -649,6 +779,26 @@ class AgreementsResource extends BaseResource {
     async create(data) {
         return this.request("POST", "/admin/agreements", data);
     }
+    /**
+     * ADR-289 — the entry point of the e-signature flow. Renders the named
+     * template against `variables` server-side and creates the resulting
+     * agreement in `draft` status with `required_signers` set — the ONLY
+     * route that can populate `required_signers` on create (plain `create()`
+     * above has no such field). Follow with `sendForSignature()` to email the
+     * signing links.
+     */
+    async createFromTemplate(params) {
+        return this.request("POST", "/admin/agreements/create-from-template", {
+            templateId: params.templateId,
+            title: params.title,
+            variables: params.variables,
+            requiredSigners: params.requiredSigners,
+            agreementType: params.agreementType,
+            description: params.description,
+            expiresInDays: params.expiresInDays,
+            otherPartyName: params.otherPartyName,
+        });
+    }
     async update(id, updates) {
         return this.request("PATCH", `/admin/agreements/${id}`, updates);
     }
@@ -661,6 +811,23 @@ class AgreementsResource extends BaseResource {
     async linkWork(id, data) {
         return this.request("POST", `/admin/agreements/${id}/works`, data);
     }
+    /**
+     * Unlink (detach) a work from an agreement (ADR-289 Wave B1 item 5 —
+     * `detach` mode on `pica_agreements_link_work`, ports the bespoke
+     * assistant's `unlink_agreement_from_work`).
+     */
+    async unlinkWork(id, workId) {
+        await this.request("DELETE", `/admin/agreements/${id}/works?work_id=${encodeURIComponent(workId)}`);
+    }
+    /**
+     * Per-signer signature status: name, signed/pending, signed_at
+     * (ADR-289 Wave B1 item 3 — backs the `signatures` section on
+     * `pica_agreements_inspect`, ports the bespoke assistant's
+     * `get_agreement_signature_status`).
+     */
+    async getSignatureStatusWithSigners(id) {
+        return this.request("GET", `/admin/agreements/${id}/signatures`);
+    }
     async sourceAgreementSplits(workId, agreementId, extractedSplits, confidence, confirm) {
         return this.request("POST", `/admin/works/${workId}/agreement-source-splits`, {
             agreement_id: agreementId,
@@ -669,6 +836,14 @@ class AgreementsResource extends BaseResource {
             confirm: confirm ?? false,
         });
     }
+    /**
+     * ADR-289 — mint a per-signer `/sign/<token>` link and email every required
+     * signer of a draft agreement. Every signer lands in exactly one of
+     * `sent`/`skipped` (with a reason) — never silently half-done.
+     */
+    async sendForSignature(id, params) {
+        return this.request("POST", `/admin/agreements/${id}/send-for-signature`, { expiresInDays: params?.expires_in_days });
+    }
 }
 // ADR-222 — sync placements as a first-class domain. REST routes implemented
 // by W4 at /api/admin/sync-placements (paired PR on the same parent feature
@@ -785,6 +960,14 @@ class MemoryResource extends BaseResource {
     async delete(id) {
         await this.request("DELETE", `/admin/memory/${id}`);
     }
+    // ADR-289 Wave C2 — pica_memory_update. Backing route is
+    // PATCH /admin/memory/[id] (lib/services/assistant-memory
+    // updateMemory); only content is exposed here (mirrors the retired
+    // bespoke assistant's handleUpdateMemory, which hard-coded
+    // source:"corrected" server-side).
+    async update(id, params) {
+        return this.request("PATCH", `/admin/memory/${id}`, params);
+    }
 }
 class NotesResource extends BaseResource {
     async list(params) {
@@ -1862,7 +2045,20 @@ class ExportResource extends BaseResource {
             qs.set("workId", params.work_id);
         if (params.work_ids && params.work_ids.length > 0)
             qs.set("workIds", params.work_ids.join(","));
-        return this.request("GET", `/admin/works/export?${qs.toString()}`);
+        const path = `/admin/works/export?${qs.toString()}`;
+        // sync-pdf is the only format returning a JSON envelope
+        // ({success, data, companyDetails}) — pro/distributor/nro stream raw
+        // `text/csv` on success (route: app/api/admin/works/export/route.ts).
+        // request() unconditionally calls response.json(), which throws parsing
+        // a CSV body — every pro/distributor/nro call 500'd with INTERNAL_ERROR
+        // (pica_export_catalog_csv: 5/5 prod errors, ops audit 2026-07-04).
+        // requestText() mirrors the ImportResource.getTemplate() precedent for
+        // the same response shape.
+        if (params.format === "sync-pdf") {
+            return this.request("GET", path);
+        }
+        const csv = await this.requestText("GET", path);
+        return { format: params.format, csv };
     }
     async songRegistration(params) {
         // Returns a signed-URL JSON envelope:
@@ -1961,6 +2157,11 @@ class SendResource extends BaseResource {
     async resend(id) {
         return this.request("POST", `/admin/send/${id}/resend`);
     }
+    // ADR-289 Wave C2 — pica_send_cancel. Backing route is
+    // DELETE /admin/send/[id] (sendHubService.cancel).
+    async cancel(id) {
+        return this.request("DELETE", `/admin/send/${id}`);
+    }
 }
 // --- Assets Resource (physical assets: equipment, instruments, studio gear) ---
 class AssetsResource extends BaseResource {
@@ -2413,6 +2614,83 @@ class ProjectsResource extends BaseResource {
     async attachWork(projectId, data) {
         return this.request("POST", `/admin/projects/${projectId}/works`, data);
     }
+    /**
+     * Detach (remove) a work from a project (ADR-289 Wave B2 item 2 —
+     * `detach` mode on `pica_projects_attach_works`, ports the bespoke
+     * assistant's `remove_work_from_project`). The work itself is not
+     * deleted — only the `project_works` junction row.
+     */
+    async detachWork(projectId, workId) {
+        await this.request("DELETE", `/admin/projects/${projectId}/works/${encodeURIComponent(workId)}`);
+    }
+    // -------------------------------------------------------------------
+    // ADR-289 Wave C1 — participants, ports the bespoke assistant's
+    // add_participants / update_participant / remove_participant /
+    // list_project_participants / get_participant_details trio.
+    //
+    // Route asymmetry (both pre-existing, not introduced here):
+    //  - PATCH /participants/[participantId] keys off the participant's
+    //    OWN row id.
+    //  - DELETE /participants/[participantId] actually keys off person_id
+    //    (route comment: "participantId here is actually the person_id
+    //    for consistency"). removeParticipant() below reproduces that
+    //    literally; callers wanting participant-id ergonomics resolve via
+    //    listParticipants() first (see ProjectsTools.manageParticipants).
+    // -------------------------------------------------------------------
+    async listParticipants(projectId) {
+        return this.request("GET", `/admin/projects/${projectId}/participants`);
+    }
+    async addParticipant(projectId, data) {
+        return this.request("POST", `/admin/projects/${projectId}/participants`, data);
+    }
+    async addParticipantsBulk(projectId, participants) {
+        return this.request("POST", `/admin/projects/${projectId}/participants`, {
+            participants,
+        });
+    }
+    /** `participantId` is the `project_participants` row id. */
+    async updateParticipant(projectId, participantId, data) {
+        return this.request("PATCH", `/admin/projects/${projectId}/participants/${encodeURIComponent(participantId)}`, data);
+    }
+    /** `personId` — the route's `[participantId]` segment is actually person_id here. */
+    async removeParticipant(projectId, personId) {
+        await this.request("DELETE", `/admin/projects/${projectId}/participants/${encodeURIComponent(personId)}`);
+    }
+    // -------------------------------------------------------------------
+    // ADR-289 Wave C1 — multimedia, ports the bespoke assistant's
+    // list_project_multimedia / add_multimedia_to_project /
+    // update_project_multimedia / remove_multimedia_from_project.
+    //
+    // Route asymmetry (both pre-existing, not introduced here):
+    //  - PATCH /multimedia/[multimediaId] keys off the `project_multimedia`
+    //    join row's OWN id.
+    //  - DELETE /multimedia/[multimediaId] keys off `multimedia_id` (the
+    //    underlying multimedia_items id), not the join row id. Callers
+    //    wanting join-row-id ergonomics resolve via listMultimedia() first
+    //    (see ProjectsTools.manageMultimedia).
+    // -------------------------------------------------------------------
+    async listMultimedia(projectId, day) {
+        const qs = day !== undefined ? `?day=${day}` : "";
+        return this.request("GET", `/admin/projects/${projectId}/multimedia${qs}`);
+    }
+    async addMultimedia(projectId, data) {
+        return this.request("POST", `/admin/projects/${projectId}/multimedia`, data);
+    }
+    async addMultimediaBulk(projectId, multimediaIds, options) {
+        return this.request("POST", `/admin/projects/${projectId}/multimedia`, {
+            multimedia_ids: multimediaIds,
+            project_day: options?.project_day,
+            allow_download: options?.allow_download,
+        });
+    }
+    /** `multimediaLinkId` is the `project_multimedia` join row's own id. */
+    async updateMultimediaLink(projectId, multimediaLinkId, data) {
+        return this.request("PATCH", `/admin/projects/${projectId}/multimedia/${encodeURIComponent(multimediaLinkId)}`, data);
+    }
+    /** `multimediaId` — the route's `[multimediaId]` segment on DELETE is the underlying multimedia_items id, not the join row id. */
+    async removeMultimediaLink(projectId, multimediaId) {
+        await this.request("DELETE", `/admin/projects/${projectId}/multimedia/${encodeURIComponent(multimediaId)}`);
+    }
 }
 class SplitSheetsResource extends BaseResource {
     async listForWork(workId) {
@@ -3121,6 +3399,25 @@ class TelegramResource extends BaseResource {
     async getPreferences() {
         return this.request("GET", "/admin/settings/telegram/notifications");
     }
+    // ADR-289 Wave C2 — pica_telegram_config write half. The REST route
+    // (POST /admin/settings/telegram/notifications) speaks camelCase
+    // (eventType/isActive/configs) — translate from the snake_case tool args
+    // here so the tool layer stays consistent with every other tool's
+    // snake_case convention.
+    async setPreferences(params) {
+        const body = {};
+        if (params.event_type !== undefined) {
+            body.eventType = params.event_type;
+            body.isActive = params.is_enabled;
+        }
+        if (params.bulk_config) {
+            body.configs = params.bulk_config.map((c) => ({
+                eventType: c.event_type,
+                isActive: c.is_enabled,
+            }));
+        }
+        return this.request("POST", "/admin/settings/telegram/notifications", body);
+    }
     // ADR-159: MCP-native Telegram pairing. Wraps the pair endpoint which
     // returns a magic code (or short-circuits on already-connected / live
     // pending code). Rate-limited to 3 new codes per user per rolling hour.
@@ -3167,6 +3464,8 @@ export class PicaClient {
     people;
     recordings;
     licensing;
+    // ADR-289 Wave C1 — internal-team booking enquiries.
+    bookings;
     credits;
     creditsBalance;
     picaScore;
@@ -3274,6 +3573,7 @@ export class PicaClient {
         this.people = new PeopleResource(baseUrl, config.apiKey, debug);
         this.recordings = new RecordingsResource(baseUrl, config.apiKey, debug);
         this.licensing = new LicensingResource(baseUrl, config.apiKey, debug);
+        this.bookings = new BookingsResource(baseUrl, config.apiKey, debug);
         this.credits = new CreditsResource(baseUrl, config.apiKey, debug);
         this.creditsBalance = new CreditsBalanceResource(baseUrl, config.apiKey, debug);
         this.picaScore = new PicaScoreResource(baseUrl, config.apiKey, debug);