@withpica/mcp-server/dist/tools/royalties.d.ts

MCP Server for withPICA — enables AI assistants to interact with your withPICA music catalog

/**
 * Royalties & Statements MCP Tools — ADR-139 Step 2
 *
 * Un-cuts the royalty data layer that was archived in the March 2026
 * UI simplification. The API routes and services still exist — these
 * tools expose them to AI assistants.
 *
 * ADR-149 (MCP tool-surface consolidation, Tier 2): pica_statements_*
 * consolidated to the query+inspect pattern.
 * - pica_statements_query replaces pica_statements_list (identical
 *   executor)
 * - pica_statements_inspect replaces pica_statements_get (identical
 *   executor, now also accepts id/statement_id as aliases for batch_id)
 * pica_statements_get was REMOVED in the mcp-server 2.93.0 WS5 removal
 * sweep (0 calls/30d in prod) and pica_statements_list in 2.99.0 (founder,
 * 2026-09-29); the getStatement and listStatements executors stay — they
 * back the query/inspect pair.
 *
 * NOTE: pica_royalties_* (list/get/unmatched/blockers/attribute) is
 * deliberately NOT part of the query/inspect fold — pica_royalties_get is an
 * earnings summary (aggregate), not a get-by-id.
 *
 * FINANCE SCOPE (mcp-server 2.93.0, 2026-07-12): every read tool here now
 * declares `scope: "read:finances"` and pica_royalties_attribute declares
 * `scope: "write:finances"` — aligning the MCP declaration with the backing
 * routes' `callerHasFinanceAccess` gate (shipped #1623) and the proxy
 * bearer-write floor (royalties/statements → write:finances). Callers
 * without finance access are now filtered from tools/list at DISCOVERY
 * instead of getting a 403 after calling. `read:finances`/`write:finances`
 * are admin-tier (not user-grantable); admin satisfies both via hasScope.
 */
import { PicaClient } from "@withpica/mcp-sdk";
import type { ToolDefinition, ToolExecutor } from "./index.js";
export declare class RoyaltiesTools {
    private pica;
    constructor(pica: PicaClient);
    getTools(): Array<{
        definition: ToolDefinition;
        executor: ToolExecutor;
    }>;
    private listPayments;
    private getEarnings;
    private getBlockers;
    private listStatements;
    private getStatement;
    private listUnmatched;
    private attributePayment;
}
/**
 * The one-line message for a song's blockers. It never calls a song clear
 * unless `state` is "clear" — the honesty rule in the tool description, made
 * true in the text an agent reads first.
 */
export declare function songBlockersMessage(result: {
    state?: string;
    blockers?: unknown[];
    unchecked?: Array<{
        reason?: string;
    }>;
}): string;
/** The one-line message for the catalogue roll-up. Same honesty rule. */
export declare function catalogueBlockersMessage(data: {
    summary?: {
        total?: number;
        clear?: number;
        blocked?: number;
        unknown?: number;
        unchecked?: unknown[];
    };
    total_listed?: number;
}): string;
//# sourceMappingURL=royalties.d.ts.map