@withpica/mcp-sdk 1.19.0 → 1.22.0

package/CHANGELOG.md

@@ -11,6 +11,61 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.22.0] - 2026-05-06
+
+### Removed
+
+- **`CreditsBalanceResource.purchase()` — credit-pack one-time purchase entry point.**
+  Retired with the move to capacity-tier subscriptions (ADR-205). The Stripe
+  Checkout endpoint, `lib/services/billing.createCreditPurchaseSession`, and
+  the `get_credit_packages` AI tool were removed in the same change. Any
+  external consumer calling `client.creditsBalance.purchase({...})` will get
+  a TypeScript compile error after upgrading.
+  - **Migration:** redirect users to the tier-subscription flow (`POST
+/admin/subscription`, exposed by the `pica_subscription_*` MCP tools or
+    the `/pricing` page CTA).
+  - **Defensive note:** the Stripe webhook handler still recognises legacy
+    `type === "credit_purchase"` metadata and awards credits if any stale
+    checkout session completes after deploy.
+  - **Breaking** — minor bump per Keep-a-Changelog convention because the
+    method has been a tombstone on the MCP surface since 2026-04-22 (B-001)
+    and was already considered an internal-only escape hatch; downstream
+    `mcp-server` (workspace consumer) was the only known caller and its
+    `purchases.ts` tool already returned `[]`. Bump if you have an external
+    consumer.
+
+## [1.21.0] - 2026-05-02
+
+### Added
+
+- **ADR-222 — `pica.syncPlacements` resource (W3, paired with W4 REST routes).**
+  Six methods on `PicaClient.syncPlacements`:
+  - `list(params?)` → `PaginatedResult<SyncPlacement>` — `GET /admin/sync-placements?<filters>`
+  - `get(id)` → `SyncPlacementWithRelations` — `GET /admin/sync-placements/{id}`
+  - `create(payload)` → `SyncPlacement` — `POST /admin/sync-placements`
+  - `update(id, patch)` → `SyncPlacement` — `PATCH /admin/sync-placements/{id}`
+  - `delete(id, opts?)` → `void` — `DELETE /admin/sync-placements/{id}`, optional `confirmation_token` query param
+  - `addSource(id, source)` → `{ placement, source }` — `POST /admin/sync-placements/{id}/sources`
+
+- **14 new exported types** mirroring `lib/services/sync-placements.ts`: `SyncPlacement`, `SyncPlacementSource`, `SyncPlacementRecording`, `SyncPlacementWithRelations`, `SyncPlacementContactInput`, `SyncPlacementRecordingInput`, `SyncPlacementSourceInput`, `CreateSyncPlacementInput`, `UpdateSyncPlacementInput`, `SyncPlacementQueryParams`, plus 4 union types (`SyncPlacementStatus`, `SyncPlacementVerificationStatus`, `SyncPlacementConfidentialityLevel`, `SyncPlacementSourceKind`). Per the SDK convention noted at top-of-file, types are duplicated across the package boundary; drift is caught by the holdout suite.
+
+- **`groups` resource (ADR-223).** New `PicaClient.groups` with four
+  methods routing to the new `/admin/groups/*` and
+  `/admin/people/{id}/groups` HTTP routes:
+  - `addMember({ group_person_id, member_person_id, role?, role_label?,
+joined_at?, receive_notifications?, notification_filter? })` —
+    server enforces parent.is_group=true via trigger; surfaces friendly
+    "is_group=true" / "already an active member" / "cannot be a member
+    of themselves" errors at 400.
+  - `removeMember({ group_person_id, member_person_id, left_at? })` —
+    sets left_at on the active row; preserves history.
+  - `listMembers(groupPersonId, { include_inactive? })` — joins to
+    people for member display fields.
+  - `listGroupsForPerson(personId, { include_inactive? })` — inverse.
+    Role enum: `member` | `founder` | `lead` | `touring_member` |
+    `session` | `guest` | `producer_in_residence`. Default
+    `receive_notifications=true` (opt-out per membership).
+
 ## [1.19.0] - 2026-04-30
 
 ### Added
@@ -50,7 +105,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Returns a discriminated union — `{ has_artwork: false }` when the
   release has no artwork on file, otherwise
   `{ has_artwork: true, base64, mime_type: "image/jpeg", width, height,
-  source_url_sha256, cache_hit }`. The discriminator avoids the
+source_url_sha256, cache_hit }`. The discriminator avoids the
   `data.data || data` falsy-unwrap trap in `BaseResource.request<T>()`
   when the server returns "no artwork" as a known state rather than a
   null payload.
@@ -93,7 +148,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **`RecordingCredit`, `RecordingCreditCreateInput`** exported as types.
   Mirror of `lib/services/recording-credits.ts` shape:
   `{recording_id, person_id?, credited_name, role, split_percentage?,
-  split_type?, display_order?, notes?}`. Roles use the 16-entry
+split_type?, display_order?, notes?}`. Roles use the 16-entry
   `RECORDING_CREDIT_ROLES` enum (no Writer/Composer — those route via
   work_credits).
 
@@ -124,7 +179,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **ADR-210 Phase 1 — `BillingSlice` + `BillingTier` types + `CatalogStats.billing_slice` field.**
   `CatalogStats` (the `pica.catalogStats()` return type) gains a four-field
   `billing_slice` object: `{ billing_state, trial_days_remaining,
-  current_tier, capacity_pct }`. Powers the symmetric stdio + HTTP fetcher
+current_tier, capacity_pct }`. Powers the symmetric stdio + HTTP fetcher
   path for `_meta.session_state`'s billing fields without forcing a new SDK
   method or endpoint into Phase 1 (see ADR-210 Stage 1 worker report Q6
   Option A). `current_tier` is `BillingTier | null` covering the full

package/dist/index.d.ts

@@ -380,6 +380,134 @@ interface AgreementWorkLink {
     royalty_split_percentage?: number;
     notes?: 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";
+type SyncPlacementSourceKind = "user_attestation" | "agreement_pdf" | "cue_sheet" | "invoice" | "email" | "screenshot" | "web" | "spreadsheet_import";
+interface SyncPlacement {
+    id: string;
+    organisation_id: string;
+    work_id: string;
+    agreement_id: string | null;
+    source_license_enquiry_id: string | null;
+    production_title: string;
+    production_type: string | null;
+    brand: string | null;
+    production_company: string | null;
+    status: SyncPlacementStatus;
+    verification_status: SyncPlacementVerificationStatus;
+    confidentiality_level: SyncPlacementConfidentialityLevel;
+    fee_amount: number | null;
+    fee_currency: string | null;
+    use_start_date: string | null;
+    use_end_date: string | null;
+    territory: string[] | null;
+    media_channels: string[] | null;
+    notes: string | null;
+    backend_expected: boolean;
+    source: string;
+    created_at: string;
+    updated_at: string;
+    created_by: string | null;
+    verified_by: string | null;
+    verified_at: string | null;
+}
+interface SyncPlacementSource {
+    id: string;
+    sync_placement_id: string;
+    url: string;
+    kind: SyncPlacementSourceKind;
+    agent_id: string | null;
+    field_coverage: string[] | null;
+    notes: string | null;
+    created_at: string;
+}
+interface SyncPlacementRecording {
+    id: string;
+    sync_placement_id: string;
+    recording_id: string;
+    role: string;
+    master_fee: number | null;
+    master_share_licensed_pct: number | null;
+    notes: string | null;
+}
+interface SyncPlacementWithRelations extends SyncPlacement {
+    recordings: SyncPlacementRecording[];
+    sources: SyncPlacementSource[];
+    agreement?: Agreement | null;
+}
+interface SyncPlacementContactInput {
+    person_id?: string;
+    person_name?: string;
+    role: string;
+    email?: string;
+    company?: string;
+    position?: string;
+    split_percentage?: number;
+}
+interface SyncPlacementRecordingInput {
+    recording_id: string;
+    role: string;
+    master_fee?: number;
+    master_share_licensed_pct?: number;
+    notes?: string;
+}
+interface SyncPlacementSourceInput {
+    url: string;
+    kind: SyncPlacementSourceKind;
+    agent_id?: string;
+    field_coverage?: string[];
+    notes?: string;
+}
+interface CreateSyncPlacementInput {
+    work_id: string;
+    production_title: string;
+    production_type?: string;
+    brand?: string;
+    production_company?: string;
+    status?: SyncPlacementStatus;
+    fee_amount?: number;
+    fee_currency?: string;
+    use_start_date?: string;
+    use_end_date?: string;
+    territory?: string[];
+    media_channels?: string[];
+    notes?: string;
+    confidentiality_level?: SyncPlacementConfidentialityLevel;
+    contacts: SyncPlacementContactInput[];
+    recordings?: SyncPlacementRecordingInput[];
+    sources?: SyncPlacementSourceInput[];
+}
+interface UpdateSyncPlacementInput {
+    status?: SyncPlacementStatus;
+    verification_status?: SyncPlacementVerificationStatus;
+    confidentiality_level?: SyncPlacementConfidentialityLevel;
+    production_title?: string;
+    production_type?: string;
+    brand?: string;
+    production_company?: string;
+    fee_amount?: number;
+    fee_currency?: string;
+    use_start_date?: string;
+    use_end_date?: string;
+    territory?: string[];
+    media_channels?: string[];
+    notes?: string;
+}
+interface SyncPlacementQueryParams {
+    work_id?: string;
+    status?: SyncPlacementStatus;
+    verification_status?: SyncPlacementVerificationStatus;
+    brand?: string;
+    production_company?: string;
+    person_id?: string;
+    recording_id?: string;
+    source_license_enquiry_id?: string;
+    min_fee?: number;
+    currency?: string;
+    limit?: number;
+    offset?: number;
+}
 interface SyncSearchParams {
     mood?: string;
     genre?: string;
@@ -580,18 +708,38 @@ declare class LicensingResource extends BaseResource {
      */
     updateEnquiryStatus(id: string, status: string, notes?: string): Promise<LicenseEnquiry>;
 }
+export interface WorkCreditAtomicAddInput {
+    person_id: string;
+    credit_type?: "writer" | "composer" | "arranger" | "lyricist" | "producer" | "performer" | "engineer" | "mixer" | "mastering" | "owner" | "vocalist" | "instrumentalist" | "conductor" | "programmer" | "remixer";
+    share_pct?: number;
+    notes?: string;
+}
+export interface AtomicCreditResult {
+    credit_id: string;
+    credit?: Record<string, unknown>;
+    work_id?: string;
+    recording_id?: string;
+}
 declare class CreditsResource extends BaseResource {
     listForWork(workId: string): Promise<WorkCredit[]>;
     updateForWork(workId: string, credits: WorkCreditsInput): Promise<WorkCredit[]>;
     listCollaborators(workId: string): Promise<WorkCredit[]>;
     updateCollaborators(workId: string, collaborators: WorkCreditsInput): Promise<WorkCredit[]>;
+    /**
+     * ADR-232 atomic add — INSERT a single work credit. Race-safe under
+     * concurrent writes (replace_work_credits is read-modify-write and
+     * therefore not atomic for this verb). Returns the new credit_id.
+     */
+    atomicAdd(workId: string, input: WorkCreditAtomicAddInput): Promise<AtomicCreditResult>;
+    /**
+     * ADR-232 atomic remove — DELETE…RETURNING with 0-row → 403
+     * INSUFFICIENT_SCOPE. No SELECT pre-probe (constant-time existence
+     * semantics — never leaks 404 vs 403 via latency).
+     */
+    atomicRemove(workId: string, creditId: string): Promise<AtomicCreditResult>;
 }
 declare class CreditsBalanceResource extends BaseResource {
     getBalance(): Promise<any>;
-    purchase(params: {
-        package_id: string;
-        currency?: string;
-    }): Promise<any>;
 }
 declare class PicaScoreResource extends BaseResource {
     get(): Promise<PicaScore>;
@@ -731,6 +879,19 @@ declare class AgreementsResource extends BaseResource {
         notes?: string;
     }): Promise<AgreementWorkLink>;
 }
+declare class SyncPlacementsResource extends BaseResource {
+    list(params?: SyncPlacementQueryParams): Promise<PaginatedResult<SyncPlacement>>;
+    get(id: string): Promise<SyncPlacementWithRelations>;
+    create(data: CreateSyncPlacementInput): Promise<SyncPlacement>;
+    update(id: string, updates: UpdateSyncPlacementInput): Promise<SyncPlacement>;
+    delete(id: string, opts?: {
+        confirmation_token?: string;
+    }): Promise<void>;
+    addSource(id: string, source: SyncPlacementSourceInput): Promise<{
+        placement: SyncPlacement;
+        source: SyncPlacementSource;
+    }>;
+}
 declare class WorkspaceResource extends BaseResource {
     getContext(): Promise<{
         organisation: {
@@ -756,6 +917,12 @@ declare class AuditResource extends BaseResource {
         since?: string;
         tool_name?: string;
         risk_level?: string;
+        /**
+         * ADR-230 — filter by declared authority tier ("read" | "draft" |
+         * "write" | "destructive"). The 4-value tier is PICA's authority
+         * detail; risk_level remains the MCP-standard 3-value hint.
+         */
+        tier?: string;
         result_status?: string;
     }): Promise<any[]>;
 }
@@ -1428,6 +1595,57 @@ declare class OpsIssuesResource extends BaseResource {
         limit?: number;
     }): Promise<MyReportedIssue[]>;
 }
+/**
+ * Reads from the Phase 4 substrate — `assistant_interactions` and
+ * `mcp_sessions`. Powers `pica_my_recent_questions` (the auditability tool)
+ * and the `pica_continue` prompt's open-loop offers.
+ *
+ * Strictly user-scoped: the API routes assert a non-null userId from the
+ * auth context and rely on RLS `(user_id = auth.uid())` for defence in depth.
+ */
+export interface RecentInteractionEntry {
+    id: string;
+    session_id: string;
+    intent: string;
+    tools_used: string[] | null;
+    prompt_excerpt: string | null;
+    result_summary: string | null;
+    success: boolean;
+    was_confirmed: boolean | null;
+    required_confirmation: boolean | null;
+    created_at: string;
+    client_name: string | null;
+    client_version: string | null;
+    transport: string;
+}
+export interface OpenLoopEntry {
+    session_id: string;
+    reason: "unconfirmed_write" | "incomplete_multi_step";
+    intent: string;
+    result_summary: string | null;
+    entity_type: string | null;
+    entity_ids: string[] | null;
+    created_at: string;
+}
+declare class AssistantInteractionsResource extends BaseResource {
+    listRecent(params?: {
+        sessionId?: string;
+        since?: string;
+        success?: boolean;
+        intent?: string;
+        limit?: number;
+    }): Promise<RecentInteractionEntry[]>;
+    detectOpenLoops(): Promise<OpenLoopEntry[]>;
+    /**
+     * ADR-226 Phase 6 — fetch the user's vocabulary context as a single
+     * pre-rendered string (or null when the user has no entries). Hit by
+     * the stdio MCP server during start(), before transport.connect, to
+     * compose handshake-time server-instructions.
+     */
+    getVocabularyContext(): Promise<{
+        instructions: string | null;
+    }>;
+}
 /**
  * Session-auth-only surface: the three HTTP routes backing these
  * methods refuse `pica_grant_` callers with 403 `session_auth_required`
@@ -1984,6 +2202,133 @@ export interface RecordingCreditCreateInput {
 declare class RecordingCreditsResource extends BaseResource {
     list(recordingId: string): Promise<RecordingCredit[]>;
     create(recordingId: string, input: RecordingCreditCreateInput): Promise<RecordingCredit>;
+    /**
+     * ADR-232 atomic add — semantically identical to `create` (a recording
+     * credit INSERT is already atomic) but reads more naturally next to
+     * CreditsResource.atomicAdd in the pica_credit_add tool implementation.
+     */
+    atomicAdd(recordingId: string, input: RecordingCreditCreateInput): Promise<AtomicCreditResult>;
+    /**
+     * ADR-232 atomic remove — DELETE with `?atomic=1` so the route returns 403
+     * INSUFFICIENT_SCOPE on 0-row instead of the legacy lenient silent
+     * success. AC-2 strict semantics for pica_credit_remove.
+     */
+    atomicRemove(recordingId: string, creditId: string): Promise<AtomicCreditResult>;
+}
+export type ShareTraceEntityType = "work" | "recording" | "person";
+export interface ShareTraceQuery {
+    entity_type: ShareTraceEntityType;
+    entity_id: string;
+    viewer_user_id?: string;
+    viewer_org_id?: string;
+}
+export interface ShareTraceReason {
+    kind: "org_membership" | "custody_chain" | "share_link" | "cross_org_grant";
+    directness: 1 | 2 | 3 | 4;
+    via_org_id?: string;
+    via_org_name?: string | null;
+    chain_hops?: Array<{
+        custodian_org_id: string;
+        custodian_org_name?: string | null;
+        percentage: number;
+        territory: string;
+    }>;
+    share_link_id?: string;
+    expires_at?: string | null;
+    grant_id?: string;
+    scope?: string[];
+    granted_at?: string | null;
+}
+export interface ShareTraceResult {
+    entity: {
+        type: ShareTraceEntityType;
+        id: string;
+        name: string;
+    };
+    viewer: {
+        type: "user" | "org";
+        id: string;
+        name: string | null;
+    };
+    has_access: boolean;
+    reasons: ShareTraceReason[];
+}
+export interface CountExplainQuery {
+    count_source: string;
+    observed_value?: number;
+}
+export interface CountExplainResult {
+    source: {
+        name: string;
+        query: string;
+        description: string;
+    };
+    computed_value: number;
+    observed_value: number | null;
+    delta: number | null;
+    delta_breakdown?: Array<{
+        reason: string;
+        count: number;
+        sample_ids: string[];
+    }>;
+}
+declare class CountExplainResource extends BaseResource {
+    /**
+     * GET /admin/count-explain — explains a single dashboard / briefing
+     * count by reproducing the canonical query and (optionally) breaking
+     * down the delta against an observed value.
+     */
+    explain(query: CountExplainQuery): Promise<CountExplainResult>;
+}
+export interface AudioPipelineStatusQuery {
+    window_days?: number;
+}
+export interface AudioPipelineByState {
+    pending: number;
+    complete: number;
+    failed: number;
+    stuck_over_24h: number;
+}
+export interface AudioPipelineStatusResult {
+    window_days: number;
+    by_state: AudioPipelineByState;
+    samples: {
+        pending: Array<{
+            audio_file_id: string;
+            work_id: string | null;
+            queued_at: string;
+        }>;
+        failed: Array<{
+            audio_file_id: string;
+            work_id: string | null;
+            error: string | null;
+            last_attempt: string | null;
+        }>;
+        stuck_over_24h: Array<{
+            audio_file_id: string;
+            work_id: string | null;
+            queued_at: string;
+            last_attempt: string | null;
+        }>;
+    };
+}
+declare class AudioPipelineStatusResource extends BaseResource {
+    /**
+     * GET /admin/audio-pipeline-status — operational read of the audio
+     * analysis pipeline state for the calling org. AC-7: every bucket is
+     * an integer (zero-org reports structured zeros, not nulls).
+     */
+    status(query?: AudioPipelineStatusQuery): Promise<AudioPipelineStatusResult>;
+}
+declare class ShareTraceResource extends BaseResource {
+    /**
+     * GET /admin/share-trace — returns the unioned chain of reasons a
+     * viewer can see an entity. AC-3: 403 + INSUFFICIENT_SCOPE if the
+     * caller doesn't own the entity (existence-leak protection). AC-4:
+     * has_access:false with reasons:[] when the caller IS the owner but
+     * the viewer can't see.
+     */
+    trace(query: ShareTraceQuery): Promise<ShareTraceResult>;
 }
 declare class RecordingSplitsResource extends BaseResource {
     list(recordingId: string): Promise<any>;
@@ -2276,6 +2621,28 @@ declare class DisputesResource extends BaseResource {
         status?: string;
     }): Promise<any>;
 }
+declare class GroupsResource extends BaseResource {
+    addMember(body: {
+        group_person_id: string;
+        member_person_id: string;
+        role?: "member" | "founder" | "lead" | "touring_member" | "session" | "guest" | "producer_in_residence";
+        role_label?: string;
+        joined_at?: string;
+        receive_notifications?: boolean;
+        notification_filter?: string[];
+    }): Promise<any>;
+    removeMember(body: {
+        group_person_id: string;
+        member_person_id: string;
+        left_at?: string;
+    }): Promise<any>;
+    listMembers(groupPersonId: string, params?: {
+        include_inactive?: boolean;
+    }): Promise<any>;
+    listGroupsForPerson(personId: string, params?: {
+        include_inactive?: boolean;
+    }): Promise<any>;
+}
 declare class ChainResource extends BaseResource {
     search(params: {
         q: string;
@@ -2312,6 +2679,7 @@ export declare class PicaClient {
     audioFiles: AudioFilesResource;
     multimedia: MultimediaResource;
     agreements: AgreementsResource;
+    syncPlacements: SyncPlacementsResource;
     workspace: WorkspaceResource;
     memory: MemoryResource;
     audit: AuditResource;
@@ -2345,6 +2713,9 @@ export declare class PicaClient {
     splitSheets: SplitSheetsResource;
     recordingSplits: RecordingSplitsResource;
     recordingCredits: RecordingCreditsResource;
+    shareTrace: ShareTraceResource;
+    countExplain: CountExplainResource;
+    audioPipelineStatus: AudioPipelineStatusResource;
     publishers: PublishersResource;
     labels: LabelsResource;
     agreementTemplates: AgreementTemplatesResource;
@@ -2365,11 +2736,13 @@ export declare class PicaClient {
     discoveries: DiscoveriesResource;
     agentIdentity: AgentIdentityResource;
     uploads: UploadsResource;
+    groups: GroupsResource;
+    assistantInteractions: AssistantInteractionsResource;
     /**
      * Get accurate catalog stats via SQL counts (no pagination limits)
      */
     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, CatalogStats, NotificationsSummary, CreateUploadSessionInput, CreateUploadSessionResult, };
+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, };
 //# sourceMappingURL=index.d.ts.map