@labelgrid/mcp 0.2.2 → 0.3.1

package/dist/api/http.d.ts

@@ -1,74 +0,0 @@
-/**
- * The single typed HTTP client for the LabelGrid public API.
- *
- * Every tool goes through this client. It owns transport, header injection,
- * query serialization, optional idempotency keys and — critically — error
- * normalization: HTTP failures are turned into a structured {@link ApiError}
- * and returned, never thrown. Business rules live server-side; this file is
- * transport only (no retries, no queues).
- */
-export type ApiError = {
-    code: string;
-    message: string;
-    status: number;
-    field?: string;
-    suggestion?: string;
-    retry_after_seconds?: number;
-    errors?: unknown;
-    /** Structured validation detail passed through verbatim from the API (422). */
-    errors_structured?: unknown;
-};
-export type ApiResult<T = unknown> = {
-    data: T;
-} | {
-    error: ApiError;
-};
-export declare class LabelGridClient {
-    private readonly baseUrl;
-    private readonly token;
-    private readonly fetchFn;
-    private readonly version;
-    private readonly timeoutMs;
-    private readonly rawTimeoutMs;
-    constructor(opts: {
-        baseUrl: string;
-        token: string;
-        fetchFn?: typeof fetch;
-        version: string;
-        /** API request timeout (default 60s) — a hung call must never hang a tool. */
-        timeoutMs?: number;
-        /** Timeout for raw transfers like presigned uploads (default 10min). */
-        rawTimeoutMs?: number;
-    });
-    private authHeaders;
-    private send;
-    /**
-     * Reads a response body with the byte ceiling enforced mid-stream. Returns
-     * the decoded text, or the supplied too-large error result when the ceiling
-     * is crossed. Abort/timeout rejections propagate to the caller for mapping.
-     */
-    private readBody;
-    get<T>(path: string, query?: Record<string, unknown>): Promise<ApiResult<T>>;
-    post<T>(path: string, body?: unknown, opts?: {
-        idempotency?: boolean;
-        idempotencyKey?: string;
-    }): Promise<ApiResult<T>>;
-    patch<T>(path: string, body?: unknown): Promise<ApiResult<T>>;
-    put<T>(path: string, body?: unknown, opts?: {
-        idempotency?: boolean;
-        idempotencyKey?: string;
-    }): Promise<ApiResult<T>>;
-    delete<T>(path: string): Promise<ApiResult<T>>;
-    /**
-     * Sends a multipart/form-data POST with a single file field plus optional
-     * extra string fields. A missing/unreadable file yields a FILE_NOT_FOUND
-     * error result rather than throwing.
-     */
-    postMultipart<T>(path: string, filePath: string, fieldName: string, extra?: Record<string, string>): Promise<ApiResult<T>>;
-    /**
-     * Performs a raw request with NO Authorization header — used for presigned
-     * upload PUTs, where the signed URL is already the credential and an extra
-     * Bearer token would break the signature.
-     */
-    raw(url: string, init: RequestInit): Promise<Response>;
-}

package/dist/api/http.js

@@ -1,392 +0,0 @@
-/**
- * The single typed HTTP client for the LabelGrid public API.
- *
- * Every tool goes through this client. It owns transport, header injection,
- * query serialization, optional idempotency keys and — critically — error
- * normalization: HTTP failures are turned into a structured {@link ApiError}
- * and returned, never thrown. Business rules live server-side; this file is
- * transport only (no retries, no queues).
- */
-import { randomUUID } from 'node:crypto';
-import { readFile } from 'node:fs/promises';
-import { basename } from 'node:path';
-import { contentType } from './content-types.js';
-/** Hard ceiling on a single response body, in bytes/characters. */
-const MAX_RESPONSE_BYTES = 10_000_000;
-const TOKEN_SUGGESTION = 'Check LABELGRID_API_TOKEN — create a new token in your dashboard under Profile → API Tokens.';
-/**
- * Serializes a query object into a URL search string, supporting nested
- * `filter[label_id]=5` objects and repeated `metrics[]=a&metrics[]=b` arrays.
- * Null/undefined values are skipped. Bracket structure is kept literal; only
- * key names and values are percent-encoded.
- */
-function buildQuery(query) {
-    if (!query)
-        return '';
-    const parts = [];
-    const push = (rawKey, value) => {
-        if (value === undefined || value === null)
-            return;
-        parts.push(`${rawKey}=${encodeURIComponent(String(value))}`);
-    };
-    for (const [key, value] of Object.entries(query)) {
-        if (value === undefined || value === null)
-            continue;
-        const ek = encodeURIComponent(key);
-        if (Array.isArray(value)) {
-            for (const item of value)
-                push(`${ek}[]`, item);
-        }
-        else if (typeof value === 'object') {
-            for (const [subKey, subValue] of Object.entries(value)) {
-                const esk = encodeURIComponent(subKey);
-                if (Array.isArray(subValue)) {
-                    for (const item of subValue)
-                        push(`${ek}[${esk}][]`, item);
-                }
-                else {
-                    push(`${ek}[${esk}]`, subValue);
-                }
-            }
-        }
-        else {
-            push(ek, value);
-        }
-    }
-    return parts.length > 0 ? `?${parts.join('&')}` : '';
-}
-/**
- * Extracts a code/message/errors triple from any of the four backend error body
- * shapes: `{message}`, `{error: string}`, `{errors}`, `{error: {code, message}}`.
- */
-function extractServerError(body) {
-    if (typeof body === 'string') {
-        return { message: body };
-    }
-    if (body === null || typeof body !== 'object') {
-        return {};
-    }
-    const record = body;
-    const errors = record.errors;
-    const errorsStructured = record.errors_structured;
-    // Shape: { error: { code, message } }
-    if (record.error !== null && typeof record.error === 'object') {
-        const nested = record.error;
-        return {
-            code: typeof nested.code === 'string' ? nested.code : undefined,
-            message: typeof nested.message === 'string'
-                ? nested.message
-                : typeof nested.error === 'string'
-                    ? nested.error
-                    : undefined,
-            errors,
-            errors_structured: errorsStructured,
-        };
-    }
-    // Shape: { error: 'string' }
-    if (typeof record.error === 'string') {
-        return {
-            code: typeof record.code === 'string' ? record.code : undefined,
-            message: record.error,
-            errors,
-            errors_structured: errorsStructured,
-        };
-    }
-    // Shapes: { message } and/or { errors } and/or top-level { code }
-    const parts = {
-        code: typeof record.code === 'string' ? record.code : undefined,
-        message: typeof record.message === 'string' ? record.message : undefined,
-        field: typeof record.field === 'string' ? record.field : undefined,
-        errors,
-        errors_structured: errorsStructured,
-    };
-    // Derive a message from the first validation error when none was given.
-    if (parts.message === undefined && errors !== null && typeof errors === 'object') {
-        const first = Object.values(errors)[0];
-        if (Array.isArray(first) && typeof first[0] === 'string') {
-            parts.message = first[0];
-        }
-        else if (typeof first === 'string') {
-            parts.message = first;
-        }
-    }
-    return parts;
-}
-function parseRetryAfter(res) {
-    const raw = res.headers.get('Retry-After');
-    if (raw === null)
-        return undefined;
-    const seconds = Number.parseInt(raw, 10);
-    return Number.isNaN(seconds) ? undefined : seconds;
-}
-/** Normalizes a non-2xx HTTP response into a structured {@link ApiError}. */
-function normalizeError(res, body) {
-    const server = extractServerError(body);
-    const status = res.status;
-    const withCommon = (code, message, extra = {}) => ({
-        code,
-        message,
-        status,
-        ...(server.field !== undefined ? { field: server.field } : {}),
-        ...(server.errors !== undefined ? { errors: server.errors } : {}),
-        ...extra,
-    });
-    switch (status) {
-        case 401:
-            return withCommon('TOKEN_INVALID', server.message ?? 'Your API token was rejected.', {
-                suggestion: TOKEN_SUGGESTION,
-            });
-        case 403:
-            return withCommon(server.code ?? 'FORBIDDEN', server.message ?? 'Forbidden.');
-        case 404:
-            return withCommon('NOT_FOUND', server.message ?? 'The requested resource was not found.');
-        case 409:
-            return withCommon(server.code ?? 'CONFLICT', server.message ?? 'The request conflicts with the current state.');
-        case 422:
-            return withCommon('VALIDATION_FAILED', server.message ?? 'The submitted data was invalid.', {
-                ...(server.errors_structured !== undefined
-                    ? { errors_structured: server.errors_structured }
-                    : {}),
-            });
-        case 429: {
-            const retryAfter = parseRetryAfter(res);
-            return withCommon('RATE_LIMITED', server.message ?? 'Rate limit exceeded.', {
-                ...(retryAfter !== undefined ? { retry_after_seconds: retryAfter } : {}),
-            });
-        }
-        default:
-            if (status >= 500) {
-                return withCommon('SERVER_ERROR', server.message ?? 'The server encountered an error.');
-            }
-            return withCommon(server.code ?? 'ERROR', server.message ?? `Request failed with status ${status}.`);
-    }
-}
-export class LabelGridClient {
-    baseUrl;
-    token;
-    fetchFn;
-    version;
-    timeoutMs;
-    rawTimeoutMs;
-    constructor(opts) {
-        this.baseUrl = opts.baseUrl.replace(/\/+$/, '');
-        this.token = opts.token;
-        this.fetchFn = opts.fetchFn ?? fetch;
-        this.version = opts.version;
-        this.timeoutMs = opts.timeoutMs ?? 60_000;
-        this.rawTimeoutMs = opts.rawTimeoutMs ?? 600_000;
-    }
-    authHeaders() {
-        return {
-            Authorization: `Bearer ${this.token}`,
-            Accept: 'application/json',
-            'User-Agent': `labelgrid-mcp/${this.version}`,
-        };
-    }
-    async send(method, path, opts = {}) {
-        const url = `${this.baseUrl}${path}${buildQuery(opts.query)}`;
-        const headers = { ...this.authHeaders(), ...opts.headers };
-        if (opts.idempotency) {
-            // A caller-supplied key is used verbatim (so a caller can dedupe a retry
-            // across separate tool calls); otherwise a fresh UUID is generated.
-            headers['Idempotency-Key'] = opts.idempotencyKey ?? randomUUID();
-        }
-        const init = { method, headers, signal: AbortSignal.timeout(this.timeoutMs) };
-        if (opts.rawBody !== undefined) {
-            init.body = opts.rawBody;
-        }
-        else if (opts.body !== undefined) {
-            headers['Content-Type'] = 'application/json';
-            init.body = JSON.stringify(opts.body);
-        }
-        let res;
-        try {
-            res = await this.fetchFn(url, init);
-        }
-        catch (err) {
-            if (err instanceof DOMException &&
-                (err.name === 'TimeoutError' || err.name === 'AbortError')) {
-                return {
-                    error: {
-                        code: 'TIMEOUT',
-                        message: `The request timed out after ${Math.round(this.timeoutMs / 1000)} seconds. Try again, or narrow the request.`,
-                        status: 0,
-                    },
-                };
-            }
-            return {
-                error: {
-                    code: 'NETWORK_ERROR',
-                    message: err instanceof Error ? err.message : 'Network request failed.',
-                    status: 0,
-                },
-            };
-        }
-        // Cheap pre-check: bound the response before reading when the length is known.
-        const declaredLength = Number.parseInt(res.headers.get('Content-Length') ?? '', 10);
-        if (!Number.isNaN(declaredLength) && declaredLength > MAX_RESPONSE_BYTES) {
-            return {
-                error: {
-                    code: 'RESPONSE_TOO_LARGE',
-                    message: `The response is ${declaredLength} bytes, over the ${MAX_RESPONSE_BYTES}-byte limit. Narrow the request with pagination or filters.`,
-                    status: res.status,
-                },
-            };
-        }
-        const tooLarge = {
-            error: {
-                code: 'RESPONSE_TOO_LARGE',
-                message: `The response body exceeds the ${MAX_RESPONSE_BYTES}-byte limit. Narrow the request with pagination or filters.`,
-                status: res.status,
-            },
-        };
-        // A chunked/streamed response carries no Content-Length, so bound it AS we
-        // read: accumulate chunks with a running byte counter and abort the moment
-        // the counter crosses the ceiling — never buffering the whole oversized body.
-        // The request timeout keeps running while the body streams, so a read can
-        // also abort here — map that to the same structured TIMEOUT.
-        let text;
-        try {
-            text = await this.readBody(res, tooLarge);
-        }
-        catch (err) {
-            if (err instanceof DOMException &&
-                (err.name === 'TimeoutError' || err.name === 'AbortError')) {
-                return {
-                    error: {
-                        code: 'TIMEOUT',
-                        message: `The request timed out after ${Math.round(this.timeoutMs / 1000)} seconds while reading the response. Try again, or narrow the request.`,
-                        status: 0,
-                    },
-                };
-            }
-            return {
-                error: {
-                    code: 'NETWORK_ERROR',
-                    message: err instanceof Error ? err.message : 'Reading the response failed.',
-                    status: 0,
-                },
-            };
-        }
-        if (typeof text !== 'string') {
-            return text; // the bounded reader returned the too-large error result
-        }
-        let body = null;
-        if (text.length > 0) {
-            try {
-                body = JSON.parse(text);
-            }
-            catch {
-                body = text;
-            }
-        }
-        if (res.ok) {
-            return { data: body };
-        }
-        return { error: normalizeError(res, body) };
-    }
-    /**
-     * Reads a response body with the byte ceiling enforced mid-stream. Returns
-     * the decoded text, or the supplied too-large error result when the ceiling
-     * is crossed. Abort/timeout rejections propagate to the caller for mapping.
-     */
-    async readBody(res, tooLarge) {
-        if (res.body) {
-            const reader = res.body.getReader();
-            const chunks = [];
-            let total = 0;
-            for (;;) {
-                const { done, value } = await reader.read();
-                if (done)
-                    break;
-                if (value) {
-                    total += value.byteLength;
-                    if (total > MAX_RESPONSE_BYTES) {
-                        // cancel() can reject (e.g. an already-errored stream); swallow it so
-                        // an oversized response ALWAYS returns RESPONSE_TOO_LARGE.
-                        try {
-                            await reader.cancel();
-                        }
-                        catch {
-                            // best-effort cleanup — the size bound is what matters here.
-                        }
-                        return tooLarge;
-                    }
-                    chunks.push(value);
-                }
-            }
-            const merged = new Uint8Array(total);
-            let offset = 0;
-            for (const chunk of chunks) {
-                merged.set(chunk, offset);
-                offset += chunk.byteLength;
-            }
-            return new TextDecoder('utf-8').decode(merged);
-        }
-        // No readable stream (some test stubs) — fall back to text() and measure
-        // the true byte length as a backstop (multi-byte chars exceed char count).
-        const text = await res.text();
-        if (Buffer.byteLength(text, 'utf8') > MAX_RESPONSE_BYTES) {
-            return tooLarge;
-        }
-        return text;
-    }
-    get(path, query) {
-        return this.send('GET', path, { query });
-    }
-    post(path, body, opts) {
-        return this.send('POST', path, {
-            body,
-            idempotency: opts?.idempotency,
-            idempotencyKey: opts?.idempotencyKey,
-        });
-    }
-    patch(path, body) {
-        return this.send('PATCH', path, { body });
-    }
-    put(path, body, opts) {
-        return this.send('PUT', path, {
-            body,
-            idempotency: opts?.idempotency,
-            idempotencyKey: opts?.idempotencyKey,
-        });
-    }
-    delete(path) {
-        return this.send('DELETE', path);
-    }
-    /**
-     * Sends a multipart/form-data POST with a single file field plus optional
-     * extra string fields. A missing/unreadable file yields a FILE_NOT_FOUND
-     * error result rather than throwing.
-     */
-    async postMultipart(path, filePath, fieldName, extra) {
-        let bytes;
-        try {
-            bytes = await readFile(filePath);
-        }
-        catch (err) {
-            return {
-                error: {
-                    code: 'FILE_NOT_FOUND',
-                    message: `Could not read file at ${filePath}: ${err instanceof Error ? err.message : 'unknown error'}`,
-                    status: 0,
-                },
-            };
-        }
-        const form = new FormData();
-        form.append(fieldName, new Blob([new Uint8Array(bytes)], { type: contentType(filePath) }), basename(filePath));
-        for (const [key, value] of Object.entries(extra ?? {})) {
-            form.append(key, value);
-        }
-        // Let fetch set the multipart Content-Type boundary; do not override it.
-        return this.send('POST', path, { rawBody: form });
-    }
-    /**
-     * Performs a raw request with NO Authorization header — used for presigned
-     * upload PUTs, where the signed URL is already the credential and an extra
-     * Bearer token would break the signature.
-     */
-    raw(url, init) {
-        return this.fetchFn(url, { signal: AbortSignal.timeout(this.rawTimeoutMs), ...init });
-    }
-}

package/dist/api/upload.d.ts

@@ -1,26 +0,0 @@
-/**
- * Presigned-URL upload helper.
- *
- * A large binary asset is never streamed through the LabelGrid API. Instead the
- * flow is three steps:
- *   1. POST the upload-url endpoint (with the filename) to mint a short-lived
- *      presigned storage URL and its object key.
- *   2. PUT the file bytes straight to that presigned URL. This request carries
- *      NO Authorization header — the signature in the URL is the credential, and
- *      an extra Bearer token would break it.
- *   3. PUT the commit endpoint with the returned object key (with an idempotency
- *      key) so the API records the finalized file.
- *
- * A failure at step 2 aborts before the commit, so a half-uploaded object is
- * never finalized. Business rules (format checks, transcoding) stay server-side.
- */
-import type { ApiResult, LabelGridClient } from './http.js';
-export type UploadOptions = {
-    /** The endpoint that mints the presigned URL, e.g. /tracks/42/files/stereo/upload-url. */
-    uploadUrlPath: string;
-    /** The endpoint that records the finalized file, e.g. /tracks/42/files/stereo. */
-    commitPath: string;
-    /** Absolute or relative local path to the file to upload. */
-    filePath: string;
-};
-export declare function uploadViaPresignedUrl(client: LabelGridClient, opts: UploadOptions): Promise<ApiResult<unknown>>;

package/dist/api/upload.js

@@ -1,104 +0,0 @@
-/**
- * Presigned-URL upload helper.
- *
- * A large binary asset is never streamed through the LabelGrid API. Instead the
- * flow is three steps:
- *   1. POST the upload-url endpoint (with the filename) to mint a short-lived
- *      presigned storage URL and its object key.
- *   2. PUT the file bytes straight to that presigned URL. This request carries
- *      NO Authorization header — the signature in the URL is the credential, and
- *      an extra Bearer token would break it.
- *   3. PUT the commit endpoint with the returned object key (with an idempotency
- *      key) so the API records the finalized file.
- *
- * A failure at step 2 aborts before the commit, so a half-uploaded object is
- * never finalized. Business rules (format checks, transcoding) stay server-side.
- */
-import { statSync } from 'node:fs';
-import { readFile } from 'node:fs/promises';
-import { basename } from 'node:path';
-import { log } from '../log.js';
-import { contentType } from './content-types.js';
-/** True only for an existing regular file. */
-function isReadableFile(p) {
-    try {
-        return statSync(p).isFile();
-    }
-    catch {
-        return false;
-    }
-}
-export async function uploadViaPresignedUrl(client, opts) {
-    // Fail fast and locally: never touch the network for a file we cannot read.
-    if (!isReadableFile(opts.filePath)) {
-        const error = {
-            code: 'FILE_NOT_FOUND',
-            message: `No readable file at ${opts.filePath}.`,
-            status: 0,
-        };
-        return { error };
-    }
-    // Step 1: mint the presigned URL.
-    const minted = await client.post(opts.uploadUrlPath, {
-        filename: basename(opts.filePath),
-    });
-    if ('error' in minted)
-        return minted;
-    const uploadUrl = minted.data?.upload_url;
-    const key = minted.data?.key;
-    if (typeof uploadUrl !== 'string' || typeof key !== 'string') {
-        const error = {
-            code: 'UPLOAD_URL_INVALID',
-            message: 'The upload-url response did not contain a usable upload_url and key.',
-            status: 0,
-        };
-        return { error };
-    }
-    // Step 2: PUT the bytes directly to storage — NO auth header (the URL is signed).
-    // The file passed isReadableFile above, but it can vanish before this read
-    // (a TOCTOU race); a structured FILE_NOT_FOUND is the contract, not a throw.
-    let bytes;
-    try {
-        bytes = await readFile(opts.filePath);
-    }
-    catch {
-        const error = {
-            code: 'FILE_NOT_FOUND',
-            message: `The file at ${opts.filePath} could not be read.`,
-            status: 0,
-        };
-        return { error };
-    }
-    let putRes;
-    try {
-        putRes = await client.raw(uploadUrl, {
-            method: 'PUT',
-            headers: { 'Content-Type': contentType(opts.filePath) },
-            body: new Uint8Array(bytes),
-        });
-    }
-    catch (err) {
-        // Never surface err.message raw to the log — it can embed the signed URL,
-        // and `reason` is not a redacted key. Strip any URL before logging.
-        log('error', 'presigned upload PUT failed', {
-            reason: err instanceof Error ? err.message.replace(/https?:\/\/\S+/gi, '[url]') : 'network error',
-        });
-        const error = {
-            code: 'UPLOAD_FAILED',
-            message: 'Uploading the file to storage failed.',
-            status: 0,
-        };
-        return { error };
-    }
-    if (!putRes.ok) {
-        // Abort BEFORE the commit — a half-uploaded object is never finalized.
-        const error = {
-            code: 'UPLOAD_FAILED',
-            message: `Uploading the file to storage failed with status ${putRes.status}.`,
-            status: putRes.status,
-        };
-        return { error };
-    }
-    // Step 3: commit the object key (idempotent — a retried commit will not duplicate).
-    return client.put(opts.commitPath, { s3_key: key }, { idempotency: true });
-}

package/dist/log.d.ts

@@ -1,16 +0,0 @@
-/**
- * stderr-only structured logging with secret redaction.
- *
- * stdout is reserved for the MCP protocol stream, so every log line goes to
- * stderr. Any structured metadata is passed through {@link redactSecrets}
- * first so tokens, passwords and signed URLs never reach the log.
- */
-/**
- * Deep-clones a value, replacing the value of any object key whose name looks
- * like a secret with a fixed mask. Non-secret values, arrays and primitives are
- * preserved (arrays and nested objects are walked recursively).
- */
-export declare function redactSecrets(v: unknown): unknown;
-export type LogLevel = 'info' | 'warn' | 'error';
-/** Writes a single redacted log line to stderr (never stdout). */
-export declare function log(level: LogLevel, msg: string, meta?: unknown): void;

package/dist/log.js

@@ -1,35 +0,0 @@
-/**
- * stderr-only structured logging with secret redaction.
- *
- * stdout is reserved for the MCP protocol stream, so every log line goes to
- * stderr. Any structured metadata is passed through {@link redactSecrets}
- * first so tokens, passwords and signed URLs never reach the log.
- */
-const SECRET_KEY = /token|password|secret|nonce|authorization|key/i;
-const MASK = '***REDACTED***';
-/**
- * Deep-clones a value, replacing the value of any object key whose name looks
- * like a secret with a fixed mask. Non-secret values, arrays and primitives are
- * preserved (arrays and nested objects are walked recursively).
- */
-export function redactSecrets(v) {
-    if (Array.isArray(v)) {
-        return v.map((item) => redactSecrets(item));
-    }
-    if (v !== null && typeof v === 'object') {
-        const out = {};
-        for (const [key, value] of Object.entries(v)) {
-            out[key] = SECRET_KEY.test(key) ? MASK : redactSecrets(value);
-        }
-        return out;
-    }
-    return v;
-}
-/** Writes a single redacted log line to stderr (never stdout). */
-export function log(level, msg, meta) {
-    let line = `[${level}] ${msg}`;
-    if (meta !== undefined) {
-        line += ` ${JSON.stringify(redactSecrets(meta))}`;
-    }
-    process.stderr.write(`${line}\n`);
-}

package/dist/tools/accounting.d.ts

@@ -1,12 +0,0 @@
-/**
- * Accounting toolset: statements, transactions, royalty breakdowns,
- * artificial-streaming records, and the account summary. All read-only.
- *
- * Two tools (`download_statement_csv`, `download_statement_invoice`) fetch a
- * file body. They validate the caller-supplied `save_to_path` and write ONLY
- * there; a CSV without a save path is returned inline, truncated at 100KB.
- * These downloads use an authenticated raw GET (the shared client's JSON path
- * would corrupt binary PDFs), with the same auth headers the client sends.
- */
-import type { ToolDef } from './types.js';
-export declare const accountingTools: ToolDef[];