@withpica/mcp-sdk 1.21.0 → 1.23.0

package/CHANGELOG.md

@@ -11,6 +11,29 @@ 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

package/dist/index.d.ts

@@ -708,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>;
@@ -891,12 +911,41 @@ declare class WorkspaceResource extends BaseResource {
         }>;
     }>;
 }
+declare class ShareSendResource extends BaseResource {
+    send(args: {
+        entity_type: "recording" | "work" | "audio_file" | "document";
+        entity_id: string;
+        recipient: {
+            kind: "user_id" | "collaborator_id" | "email";
+            value: string;
+        };
+        note?: string;
+        expires_in_days?: number;
+        scope?: "view" | "view+download";
+        confirm_first_external_send?: boolean;
+    }): Promise<{
+        send_id: string;
+        share_link_id: string;
+        share_url: string;
+        recipient_resolution: {
+            classification: "internal_user" | "internal_contact" | "external";
+            display_name: string | null;
+            email_hash_prefix: string;
+        };
+    }>;
+}
 declare class AuditResource extends BaseResource {
     list(params?: {
         limit?: number;
         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[]>;
 }
@@ -1569,6 +1618,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`
@@ -2125,6 +2225,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>;
@@ -2464,6 +2691,60 @@ declare class ImportDocumentsResource extends BaseResource {
     get(id: string): Promise<any>;
     ingest(content: string): Promise<any>;
 }
+export type AccessSimulateEntityType = "work" | "recording" | "person" | "release";
+export type AccessSimulateAction = "view" | "share_link_preview" | "claim" | "grant";
+export type AccessSimulateRecipientType = "user" | "anonymous" | "share_link";
+export interface AccessSimulateShareLinkConfig {
+    access_type: "private" | "limited" | "public";
+    allow_download?: boolean;
+    allow_streaming?: boolean;
+    allow_comments?: boolean;
+    allow_view_collaborators?: boolean;
+    allow_view_financials?: boolean;
+    watermark_audio?: boolean;
+    notify_on_access?: boolean;
+    allowed_person_ids?: string[];
+    sent_to_emails?: string[];
+    max_views?: number | null;
+    expires_at?: string | null;
+}
+export interface AccessSimulateInput {
+    entity_type: AccessSimulateEntityType;
+    entity_id: string;
+    action: AccessSimulateAction;
+    recipient: {
+        type: AccessSimulateRecipientType;
+        user_id?: string;
+        org_id?: string;
+        share_config?: AccessSimulateShareLinkConfig;
+    };
+}
+export type AccessSimulateRuleName = "rls" | "share_link" | "collaborator" | "cross_org_grant" | "identity_inheritance" | "not_yet_supported" | "entity_not_found";
+export interface AccessSimulateReason {
+    rule: AccessSimulateRuleName;
+    decision: "allow" | "deny" | "info";
+    detail: string;
+    applies_to?: string[];
+}
+export interface AccessSimulateWarning {
+    severity: "info" | "warn" | "error";
+    message: string;
+}
+export interface AccessSimulateResult {
+    entity_type: AccessSimulateEntityType;
+    entity_id: string;
+    action: AccessSimulateAction;
+    visible: boolean;
+    visible_fields: string[];
+    hidden_fields: string[];
+    visible_relations: Record<string, "visible" | "hidden" | "watermarked">;
+    reasons: AccessSimulateReason[];
+    warnings: AccessSimulateWarning[];
+    not_yet_supported?: boolean;
+}
+declare class AccessSimulateResource extends BaseResource {
+    simulate(input: AccessSimulateInput): Promise<AccessSimulateResult>;
+}
 export declare class PicaClient {
     works: WorksResource;
     people: PeopleResource;
@@ -2509,6 +2790,9 @@ export declare class PicaClient {
     splitSheets: SplitSheetsResource;
     recordingSplits: RecordingSplitsResource;
     recordingCredits: RecordingCreditsResource;
+    shareTrace: ShareTraceResource;
+    countExplain: CountExplainResource;
+    audioPipelineStatus: AudioPipelineStatusResource;
     publishers: PublishersResource;
     labels: LabelsResource;
     agreementTemplates: AgreementTemplatesResource;
@@ -2530,6 +2814,9 @@ export declare class PicaClient {
     agentIdentity: AgentIdentityResource;
     uploads: UploadsResource;
     groups: GroupsResource;
+    assistantInteractions: AssistantInteractionsResource;
+    shareSend: ShareSendResource;
+    accessSimulate: AccessSimulateResource;
     /**
      * Get accurate catalog stats via SQL counts (no pagination limits)
      */