@withpica/mcp-sdk 3.1.1 → 3.3.0

package/CHANGELOG.md

@@ -11,6 +11,37 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.3.0] - 2026-07-04
+
+### Added
+
+- `agreements.createFromTemplate(params)` — render a template and create the
+  resulting agreement in `draft` status with `required_signers` set. The
+  only SDK method that can populate `required_signers` on create; follow
+  with `agreements.sendForSignature()` (ADR-289 — entry point of the
+  e-signature flow).
+
+## [3.2.0] - 2026-07-04
+
+### Added
+
+- `agreements.sendForSignature(id, { expires_in_days })` — dispatch per-signer
+  signing-link emails for an agreement (ADR-289 Wave A).
+- `BookingsResource` — query/detail/update for booking enquiries (ADR-289 Wave C).
+- Project participant + multimedia management methods on `ProjectsResource`,
+  and work detach support (ADR-289 Wave C).
+- Artist-projects and people-triangulate methods (ADR-289 Wave B).
+- `agreements.getSignatureStatusWithSigners(id)` — per-signer signature status
+  (ADR-289 Wave B).
+- Memory update, telegram notification config, and send-hub cancel methods
+  (ADR-289 Wave C).
+
+### Changed
+
+- `Work` type declares the licensing fields (`training_rights`, `is_licensable`,
+  `available_for_licensing`, `licensing_terms`, `licensing_price_usd`,
+  `licensing_notes`); `Person` declares `name`. Types-only, additive.
+
 ## [3.1.1] - 2026-07-01
 
 ### Added

package/dist/index.d.ts

@@ -306,11 +306,19 @@ interface Work {
     completeness_score?: number | null;
     ai_disclosure?: Record<string, unknown>;
     provenance_attestation?: Record<string, unknown>;
+    training_rights?: Record<string, unknown>;
+    is_licensable?: boolean | null;
+    available_for_licensing?: boolean | null;
+    licensing_terms?: string | null;
+    licensing_price_usd?: number | null;
+    licensing_notes?: string | null;
     created_at: string;
     updated_at: string;
 }
 interface Person {
     id: string;
+    /** Canonical display name (people.name — often a stage name). */
+    name?: string;
     first_name?: string;
     last_name?: string;
     email?: string;
@@ -464,6 +472,41 @@ interface AgreementWorkLink {
     royalty_split_percentage?: number;
     notes?: string;
 }
+/** ADR-289 — why a required signer was NOT sent a ready-to-sign email. */
+type AgreementSendForSignatureSkipReason = "no_email_on_file" | "already_signed" | "link_mint_failed" | "email_send_failed";
+interface AgreementSendForSignatureSentEntry {
+    person_id: string;
+    name: string;
+}
+interface AgreementSendForSignatureSkippedEntry {
+    person_id: string;
+    name: string;
+    reason: AgreementSendForSignatureSkipReason;
+}
+/** ADR-289 — every required signer lands in exactly one of sent/skipped. */
+interface AgreementSendForSignatureResult {
+    agreement_id: string;
+    status: string;
+    sent: AgreementSendForSignatureSentEntry[];
+    skipped: AgreementSendForSignatureSkippedEntry[];
+}
+/**
+ * ADR-289 — the ONLY request shape that can set `required_signers` on a
+ * draft agreement. Mirrors `CreateAgreementFromTemplateParams` in
+ * `lib/services/electronic-signature.ts` (camelCase body — the route reads
+ * `templateId`/`requiredSigners`/etc off the raw JSON, not snake_case).
+ */
+interface CreateAgreementFromTemplateParams {
+    templateId: string;
+    title: string;
+    variables: Record<string, unknown>;
+    requiredSigners: string[];
+    agreementType: string;
+    description?: string;
+    expiresInDays?: number;
+    /** Derived from the first required signer's person record when omitted. */
+    otherPartyName?: string;
+}
 type SyncPlacementStatus = "licensed" | "aired" | "expired" | "renewed" | "terminated";
 type SyncPlacementVerificationStatus = "unverified" | "self_attested" | "evidence_attached" | "operator_verified" | "disputed";
 type SyncPlacementConfidentialityLevel = "public" | "redacted_in_public_car" | "private";
@@ -671,6 +714,40 @@ interface LicenseEnquiry {
     created_at: string;
     updated_at: string;
 }
+/**
+ * ADR-289 Wave C1 — ports the bespoke assistant's booking-enquiry tools
+ * (search_booking_inquiries / get_booking_enquiry_details /
+ * update_booking_enquiry_status / record_booking_response /
+ * set_booking_follow_up). Mirrors `lib/services/booking.ts`'s
+ * `BookingEnquiry` shape.
+ */
+interface BookingEnquiry {
+    id: string;
+    created_at: string;
+    updated_at: string;
+    organisation_id: string;
+    name: string;
+    email: string;
+    phone: string | null;
+    enquiry_type: string;
+    service_id: string | null;
+    project_title: string | null;
+    project_description: string;
+    budget_range: string | null;
+    timeline: string | null;
+    deadline: string | null;
+    status: string;
+    priority: string;
+    response_sent_at: string | null;
+    response_content: string | null;
+    responded_by: string | null;
+    follow_up_required: boolean;
+    follow_up_date: string | null;
+    internal_notes: string | null;
+    source: string | null;
+    referrer: string | null;
+    metadata: Record<string, unknown> | null;
+}
 export declare class ApiError extends Error {
     status: number;
     retryable: boolean;
@@ -731,6 +808,20 @@ declare class BaseResource {
     private fetchWithTimeout;
     private fetchWithRetry;
     protected request<T>(method: string, path: string, body?: any): Promise<T>;
+    /**
+     * 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.
+     */
+    protected requestText(method: string, path: string): Promise<string>;
     /**
      * Make a request and return paginated result with metadata
      */
@@ -878,6 +969,40 @@ declare class PeopleResource extends BaseResource {
     enrichFromISNI(id: string, isni: string): Promise<Person>;
     enrichFromMusicBrainz(id: string, musicbrainz_id: string): Promise<Person>;
     bulkDelete(ids: string[]): Promise<unknown>;
+    /**
+     * 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`).
+     */
+    listArtistProjects(personId: string): Promise<{
+        projects: unknown[];
+        total: number;
+    }>;
+    /**
+     * 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`).
+     */
+    enrichArtistProjects(personId: string): Promise<Record<string, unknown>>;
+    /**
+     * 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`).
+     */
+    setPrimaryArtistProject(artistProjectId: string): Promise<Record<string, unknown>>;
+    /**
+     * 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).
+     */
+    triangulate(params: {
+        artist_name: string;
+        musicbrainz_id?: string;
+    }): Promise<Record<string, unknown>>;
 }
 declare class LicensingResource extends BaseResource {
     /**
@@ -907,6 +1032,48 @@ declare class LicensingResource extends BaseResource {
      * Update a license enquiry status
      */
     updateEnquiryStatus(id: string, status: string, notes?: string): Promise<LicenseEnquiry>;
+    /**
+     * 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.
+     */
+    setLicenseEnquiryCounterOffer(id: string, counterOffer: number, notes?: string): Promise<LicenseEnquiry>;
+}
+/**
+ * ADR-289 Wave C1 — booking enquiries (internal-team session/production
+ * bookings, distinct from `LicensingResource`'s sync-license enquiries).
+ * Wraps `/admin/bookings` + `/admin/bookings/[id]`.
+ */
+declare class BookingsResource extends BaseResource {
+    /**
+     * List/search booking enquiries. `GET /admin/bookings` returns the raw
+     * array (not `{data, count}`) — `request()` unwraps to that array.
+     */
+    list(params?: {
+        status?: string;
+        priority?: string;
+        query?: string;
+        enquiry_type?: string;
+        follow_up_required?: boolean;
+        limit?: number;
+        offset?: number;
+    }): Promise<BookingEnquiry[]>;
+    get(id: string): Promise<BookingEnquiry>;
+    /**
+     * `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).
+     */
+    update(id: string, data: {
+        status?: string;
+        responseContent?: string;
+        respondedBy?: "pica" | "manual";
+        followUp?: boolean;
+        followUpDate?: string;
+    }): Promise<BookingEnquiry>;
 }
 export interface WorkCreditAtomicAddInput {
     person_id: string;
@@ -1099,6 +1266,14 @@ declare class AgreementsResource extends BaseResource {
         status?: string;
         party_name?: string;
         includeWorkCounts?: boolean;
+        /**
+         * ADR-289 Wave B1 item 4 — filter to agreements in `pending_signature`
+         * or `partially_signed` (ports the bespoke assistant's
+         * `list_pending_signatures`). Maps to `?awaiting_signature=true` on the
+         * route, which already had multi-status filtering (`statuses[]`) under
+         * the hood.
+         */
+        awaiting_signature?: boolean;
         limit?: number;
         offset?: number;
     }): Promise<Agreement[]>;
@@ -1108,6 +1283,15 @@ declare class AgreementsResource extends BaseResource {
         linkedWorks: unknown[];
     }>;
     create(data: Partial<Agreement>): Promise<Agreement>;
+    /**
+     * 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.
+     */
+    createFromTemplate(params: CreateAgreementFromTemplateParams): Promise<Agreement>;
     update(id: string, updates: Partial<Agreement>): Promise<Agreement>;
     delete(id: string): Promise<void>;
     getWorks(id: string): Promise<AgreementWorkLink[]>;
@@ -1116,11 +1300,46 @@ declare class AgreementsResource extends BaseResource {
         royalty_split_percentage?: number;
         notes?: string;
     }): Promise<AgreementWorkLink>;
+    /**
+     * 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`).
+     */
+    unlinkWork(id: string, workId: string): Promise<void>;
+    /**
+     * 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`).
+     */
+    getSignatureStatusWithSigners(id: string): Promise<{
+        agreementId: string;
+        status: string;
+        requiredSignatureCount: number;
+        signatureCount: number;
+        isFullySigned: boolean;
+        expiresAt: string | null;
+        daysUntilExpiry: number | null;
+        signers: Array<{
+            person_id: string;
+            name: string | null;
+            status: "signed" | "pending";
+            signed_at: string | null;
+        }>;
+    }>;
     sourceAgreementSplits(workId: string, agreementId: string, extractedSplits: Array<{
         person_id?: string;
         name?: string;
         percentage: number;
     }>, confidence: number, confirm?: boolean): Promise<any>;
+    /**
+     * 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.
+     */
+    sendForSignature(id: string, params?: {
+        expires_in_days?: number;
+    }): Promise<AgreementSendForSignatureResult>;
 }
 declare class SyncPlacementsResource extends BaseResource {
     list(params?: SyncPlacementQueryParams): Promise<PaginatedResult<SyncPlacement>>;
@@ -1226,6 +1445,9 @@ declare class MemoryResource extends BaseResource {
         type?: string;
     }): Promise<any>;
     delete(id: string): Promise<void>;
+    update(id: string, params: {
+        content: string;
+    }): Promise<any>;
 }
 declare class NotesResource extends BaseResource {
     list(params?: {
@@ -2393,6 +2615,7 @@ declare class SendResource extends BaseResource {
     }>;
     listPending(): Promise<Array<Record<string, unknown>>>;
     resend(id: string): Promise<Record<string, unknown>>;
+    cancel(id: string): Promise<Record<string, unknown>>;
 }
 declare class AssetsResource extends BaseResource {
     list(params?: {
@@ -2678,11 +2901,18 @@ declare class ImportResource extends BaseResource {
         selectedVideoIds?: string[];
         targetWorkId?: string;
         overrideVersionType?: string;
+        /**
+         * ADR-289 Wave B2 item 1 — when true, a video already linked to a
+         * recording in this org has its stats re-fetched and updated
+         * instead of being re-imported as a duplicate.
+         */
+        refresh?: boolean;
     }): Promise<{
         recordingsCreated: number;
         worksCreated: number;
         worksMatched: number;
         multimediaLinked: number;
+        refreshed: number;
         workIds: string[];
         items: Array<{
             videoId: string;
@@ -2690,7 +2920,7 @@ declare class ImportResource extends BaseResource {
             recordingId: string | null;
             versionType: string;
             matched: boolean;
-            status: "created" | "skipped" | "error";
+            status: "created" | "skipped" | "refreshed" | "error";
             error?: string;
         }>;
     }>;
@@ -3033,6 +3263,52 @@ declare class ProjectsResource extends BaseResource {
         project_day?: number | null;
         notes?: string | null;
     }): Promise<any>;
+    /**
+     * 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.
+     */
+    detachWork(projectId: string, workId: string): Promise<void>;
+    listParticipants(projectId: string): Promise<any>;
+    addParticipant(projectId: string, data: {
+        person_id: string;
+        role?: string;
+        notes?: string;
+    }): Promise<any>;
+    addParticipantsBulk(projectId: string, participants: Array<{
+        person_id: string;
+        role?: string;
+        notes?: string;
+    }>): Promise<any>;
+    /** `participantId` is the `project_participants` row id. */
+    updateParticipant(projectId: string, participantId: string, data: {
+        role?: string | null;
+        status?: string;
+        notes?: string;
+    }): Promise<any>;
+    /** `personId` — the route's `[participantId]` segment is actually person_id here. */
+    removeParticipant(projectId: string, personId: string): Promise<void>;
+    listMultimedia(projectId: string, day?: number): Promise<any>;
+    addMultimedia(projectId: string, data: {
+        multimedia_id: string;
+        project_day?: number;
+        notes?: string;
+        allow_download?: boolean;
+    }): Promise<any>;
+    addMultimediaBulk(projectId: string, multimediaIds: string[], options?: {
+        project_day?: number;
+        allow_download?: boolean;
+    }): Promise<any>;
+    /** `multimediaLinkId` is the `project_multimedia` join row's own id. */
+    updateMultimediaLink(projectId: string, multimediaLinkId: string, data: {
+        project_day?: number | null;
+        notes?: string | null;
+        display_order?: number;
+        allow_download?: boolean;
+    }): Promise<any>;
+    /** `multimediaId` — the route's `[multimediaId]` segment on DELETE is the underlying multimedia_items id, not the join row id. */
+    removeMultimediaLink(projectId: string, multimediaId: string): Promise<void>;
 }
 declare class SplitSheetsResource extends BaseResource {
     listForWork(workId: string): Promise<any>;
@@ -3754,6 +4030,14 @@ declare class TelegramResource extends BaseResource {
     getStatus(): Promise<any>;
     sendNotification(message: string): Promise<any>;
     getPreferences(): Promise<any>;
+    setPreferences(params: {
+        event_type?: string;
+        is_enabled?: boolean;
+        bulk_config?: Array<{
+            event_type: string;
+            is_enabled: boolean;
+        }>;
+    }): Promise<any>;
     connect(): Promise<any>;
 }
 declare class ImportDocumentsResource extends BaseResource {
@@ -3838,6 +4122,7 @@ export declare class PicaClient {
     people: PeopleResource;
     recordings: RecordingsResource;
     licensing: LicensingResource;
+    bookings: BookingsResource;
     credits: CreditsResource;
     creditsBalance: CreditsBalanceResource;
     picaScore: PicaScoreResource;
@@ -3920,5 +4205,5 @@ export declare class PicaClient {
     catalogStats(): Promise<CatalogStats>;
     constructor(config: PicaClientConfig);
 }
-export type { Work, Person, Recording, PaginatedResult, PicaClientConfig, SyncSearchParams, SyncTrack, SyncSearchResult, LicenseEnquiryInput, LicenseEnquiry, WorkCredit, WorkCreditsInput, PicaScore, PicaScorePillar, AudioFile, AudioAnalysisStatus, PresignedUploadResult, CompleteUploadResult, IdentifyResult, MultimediaItem, Agreement, AgreementWorkLink, SyncPlacement, SyncPlacementSource, SyncPlacementRecording, SyncPlacementWithRelations, SyncPlacementContactInput, SyncPlacementRecordingInput, SyncPlacementSourceInput, CreateSyncPlacementInput, UpdateSyncPlacementInput, SyncPlacementQueryParams, SyncPlacementStatus, SyncPlacementVerificationStatus, SyncPlacementConfidentialityLevel, SyncPlacementSourceKind, CatalogStats, NotificationsSummary, CreateUploadSessionInput, CreateUploadSessionResult, };
+export type { Work, Person, Recording, PaginatedResult, PicaClientConfig, SyncSearchParams, SyncTrack, SyncSearchResult, LicenseEnquiryInput, LicenseEnquiry, BookingEnquiry, WorkCredit, WorkCreditsInput, PicaScore, PicaScorePillar, AudioFile, AudioAnalysisStatus, PresignedUploadResult, CompleteUploadResult, IdentifyResult, MultimediaItem, Agreement, AgreementWorkLink, CreateAgreementFromTemplateParams, AgreementSendForSignatureResult, AgreementSendForSignatureSentEntry, AgreementSendForSignatureSkippedEntry, AgreementSendForSignatureSkipReason, SyncPlacement, SyncPlacementSource, SyncPlacementRecording, SyncPlacementWithRelations, SyncPlacementContactInput, SyncPlacementRecordingInput, SyncPlacementSourceInput, CreateSyncPlacementInput, UpdateSyncPlacementInput, SyncPlacementQueryParams, SyncPlacementStatus, SyncPlacementVerificationStatus, SyncPlacementConfidentialityLevel, SyncPlacementSourceKind, CatalogStats, NotificationsSummary, CreateUploadSessionInput, CreateUploadSessionResult, };
 //# sourceMappingURL=index.d.ts.map