@labelgrid/mcp 0.3.0 → 0.4.0

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/entities.d.ts

@@ -1,25 +0,0 @@
-/**
- * The catalog-entity registry: the six entity kinds the consolidated catalog
- * tools operate on, each with its endpoint path and the reviewed documentation
- * fragments (list filters, create/update fields, delete refusals) the tool
- * descriptions are assembled from.
- *
- * This is data, not behavior — the catalog tools stay thin wrappers and the
- * API owns all validation. The wording here carries the caveats from the
- * per-entity tool descriptions it replaces (recording_country on track create,
- * RELEASE_LOCKED_FIELDS on release update, the delete refusals).
- */
-export type EntityName = 'label' | 'artist' | 'writer' | 'publisher' | 'release' | 'track';
-/** The entity names as a tuple, for zod enum inputs. */
-export declare const ENTITY_NAMES: readonly ["label", "artist", "writer", "publisher", "release", "track"];
-export type EntitySpec = {
-    /** The collection endpoint path, e.g. '/labels'. */
-    path: string;
-    /** One-line doc of the useful list filters for search_catalog. */
-    filtersDoc: string;
-    /** One-line doc of required + common create/update fields. */
-    fieldsDoc: string;
-    /** One-line doc of the server-side delete refusals. */
-    deleteNote: string;
-};
-export declare const ENTITIES: Record<EntityName, EntitySpec>;

package/dist/entities.js

@@ -1,51 +0,0 @@
-/**
- * The catalog-entity registry: the six entity kinds the consolidated catalog
- * tools operate on, each with its endpoint path and the reviewed documentation
- * fragments (list filters, create/update fields, delete refusals) the tool
- * descriptions are assembled from.
- *
- * This is data, not behavior — the catalog tools stay thin wrappers and the
- * API owns all validation. The wording here carries the caveats from the
- * per-entity tool descriptions it replaces (recording_country on track create,
- * RELEASE_LOCKED_FIELDS on release update, the delete refusals).
- */
-/** The entity names as a tuple, for zod enum inputs. */
-export const ENTITY_NAMES = ['label', 'artist', 'writer', 'publisher', 'release', 'track'];
-export const ENTITIES = {
-    label: {
-        path: '/labels',
-        filtersDoc: 'label: no documented filters — paginate with page/per_page.',
-        fieldsDoc: 'label — required: name, default_email; optional: support email, website/platform URLs, default copyright lines, isrc_base.',
-        deleteNote: 'label: refused while the label still has releases — remove or reassign its releases first.',
-    },
-    artist: {
-        path: '/artists',
-        filtersDoc: 'artist: artist_name (filter by artist name).',
-        fieldsDoc: 'artist — required: artist_name; optional: full_name, email, location, bios, isni, default_language, platform profile URLs.',
-        deleteNote: 'artist: refused while still referenced by releases or tracks.',
-    },
-    writer: {
-        path: '/writers',
-        filtersDoc: 'writer: name (writer name), ipi (IPI number).',
-        fieldsDoc: 'writer — required: first_name, last_name; optional: middle_name, display_credits, email, country, pro, ipi, isni, publisher_id (or publisher_name/publisher_pro/publisher_ipi).',
-        deleteNote: 'writer: refused while still referenced by tracks.',
-    },
-    publisher: {
-        path: '/publishers',
-        filtersDoc: 'publisher: name (publisher name), ipi (IPI number).',
-        fieldsDoc: 'publisher — required: name; optional: ipi, pro, isni, controlled_publisher.',
-        deleteNote: 'publisher: refused while still referenced by writers.',
-    },
-    release: {
-        path: '/releases',
-        filtersDoc: 'release: label_id (owning label id), is_live (1 = live/distributed only), barcode_number (UPC/EAN), cat (catalog number).',
-        fieldsDoc: 'release — required on create: content_type, label_id, artists, titles, cat (catalog number), artwork_ai_usage, primary_genre_id; many optional fields (dates, copyright lines, genres, per-outlet URLs). Once submitted or distributed some fields are locked — changing one returns a 403 with code RELEASE_LOCKED_FIELDS naming exactly which fields cannot change.',
-        deleteNote: 'release: only a never-submitted draft can be deleted.',
-    },
-    track: {
-        path: '/tracks',
-        filtersDoc: 'track: release_id (one release’s tracks), isrc (filter by ISRC).',
-        fieldsDoc: 'track — required on create: release_id, disc, track_num, composition_type, artists, audio_ai_usage, composition_ai_usage, commercial_samples, audio_language, contributors, and recording_country (ISO 3166-1 alpha-2, e.g. "US"); optional: titles, isrc, iswc, writers, publishers, splits, and more.',
-        deleteNote: 'track: allowed while the parent release is an editable draft; refused once submitted or distributed.',
-    },
-};

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`);
-}