@labelgrid/core 0.1.0 → 0.2.1

package/CHANGELOG.md

@@ -8,6 +8,55 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 `@labelgrid/core` is primarily an internal shared client for the LabelGrid MCP
 server and CLI — there are no API-stability promises before 1.0.
 
+## [0.2.1] - 2026-08-05
+
+### Changed
+
+- The catalog entity descriptions carried by this package were tightened. The
+  `RELEASE_LOCKED_FIELDS` caveat now lives only on the tool it applies to
+  instead of being repeated for every entity. Field requirements, paths and
+  exported types are unchanged.
+
+## [0.2.0] - 2026-07-23
+
+### Added
+
+- `MAX_UPLOAD_BYTES` (4 GiB) upload ceiling and a `FILE_TOO_LARGE` structured
+  error. An oversized file is now rejected with an honest size-and-limit
+  message instead of being mislabeled `FILE_NOT_FOUND`.
+- `mintUpload`, `putToPresignedUrl` and `commitUpload` — the presigned upload
+  flow's three steps are now individually exported and composed by
+  `uploadViaPresignedUrl`, so an alternate transport can reuse mint + commit and
+  swap only the byte-transfer step. Pure refactor; no behavior change.
+- `LabelGridClient.getRaw(path, query?)` — an authenticated raw GET for file
+  downloads that returns the live response for streaming, or the same
+  normalized structured error as the JSON path, honoring the raw transfer
+  timeout. Consolidates the duplicated authed-download helpers that lived in the
+  MCP and CLI packages.
+
+### Changed
+
+- Presigned-URL uploads now stream the file from disk with an explicit
+  `Content-Length` header instead of buffering the whole file into memory, so
+  peak memory stays flat regardless of file size. (An explicit `Content-Length`
+  is required — S3-compatible presigned PUTs reject a chunked body with 411.)
+- Multipart uploads no longer make a redundant in-memory copy of the file bytes
+  before building the form Blob.
+- `UploadOptions` accepts an optional `onProgress` callback, invoked with the
+  running byte count as the presigned PUT streams (for a transfer-progress UI).
+
+### Fixed
+
+- Multipart uploads (cover art, license documents) now use the longer raw
+  transfer timeout instead of the 60s JSON request timeout, so a large file on
+  a slow uplink is no longer aborted mid-upload.
+- `raw()` now composes a caller-supplied `AbortSignal` with the transfer-timeout
+  signal (`AbortSignal.any`) instead of letting the caller's signal silently
+  replace and disable the timeout.
+- Presigned-upload progress reporting now forwards a source-stream error onto
+  the composed request body, so a file that becomes unreadable mid-transfer
+  fails cleanly as `UPLOAD_FAILED` instead of raising an unhandled stream error.
+
 ## [0.1.0] - 2026-07-20
 
 ### Added

package/dist/api/http.d.ts

@@ -23,6 +23,17 @@ export type ApiResult<T = unknown> = {
 } | {
     error: ApiError;
 };
+/**
+ * The outcome of a raw authenticated GET: either the live {@link Response} (for
+ * the caller to stream a file body from) or a normalized structured error.
+ */
+export type RawResult = {
+    ok: true;
+    res: Response;
+} | {
+    ok: false;
+    error: ApiError;
+};
 export declare class LabelGridClient {
     private readonly baseUrl;
     private readonly token;
@@ -74,4 +85,16 @@ export declare class LabelGridClient {
      * Bearer token would break the signature.
      */
     raw(url: string, init: RequestInit): Promise<Response>;
+    /**
+     * Authenticated raw GET for file-body downloads (statement CSV/PDF): sends the
+     * same auth headers as the JSON path but returns the live {@link Response} on
+     * success so the caller streams the body to disk, never buffering a large file
+     * in memory. A non-2xx is read and normalized to the same structured
+     * {@link ApiError} as the JSON path; a network/timeout failure maps to the same
+     * NETWORK_ERROR/TIMEOUT. Uses the longer raw transfer timeout, since a download
+     * is a byte transfer, not a JSON call.
+     */
+    getRaw(path: string, query?: Record<string, unknown>): Promise<RawResult>;
+    /** Maps a fetch rejection (abort/timeout vs other) to a structured error. */
+    private mapFetchError;
 }

package/dist/api/http.js

@@ -193,7 +193,11 @@ export class LabelGridClient {
             // 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) };
+        // A raw body is a byte transfer (a multipart upload), not a JSON call — it
+        // gets the longer transfer timeout so a large file on a slow uplink is not
+        // aborted at the 60s JSON deadline.
+        const effectiveTimeoutMs = opts.rawBody !== undefined ? this.rawTimeoutMs : this.timeoutMs;
+        const init = { method, headers, signal: AbortSignal.timeout(effectiveTimeoutMs) };
         if (opts.rawBody !== undefined) {
             init.body = opts.rawBody;
         }
@@ -211,7 +215,7 @@ export class LabelGridClient {
                 return {
                     error: {
                         code: 'TIMEOUT',
-                        message: `The request timed out after ${Math.round(this.timeoutMs / 1000)} seconds. Try again, or narrow the request.`,
+                        message: `The request timed out after ${Math.round(effectiveTimeoutMs / 1000)} seconds. Try again, or narrow the request.`,
                         status: 0,
                     },
                 };
@@ -257,7 +261,7 @@ export class LabelGridClient {
                 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.`,
+                        message: `The request timed out after ${Math.round(effectiveTimeoutMs / 1000)} seconds while reading the response. Try again, or narrow the request.`,
                         status: 0,
                     },
                 };
@@ -376,7 +380,20 @@ export class LabelGridClient {
             };
         }
         const form = new FormData();
-        form.append(fieldName, new Blob([new Uint8Array(bytes)], { type: contentType(filePath) }), basename(filePath));
+        // Wrap the buffer's bytes in a zero-copy Uint8Array VIEW (same underlying
+        // memory, honoring byteOffset/byteLength on a pooled Buffer), which the Blob
+        // then copies once. The previous `new Blob([new Uint8Array(bytes)])` made an
+        // extra full copy before the Blob's own copy — that redundant copy is gone.
+        // Node's FormData accepts a Blob field. Streaming multipart is not practical
+        // with undici's FormData (it materializes the parts), so this stays a single
+        // in-memory buffer — acceptable for the small files (images, PDFs, lyrics)
+        // that use the multipart path; the large binaries go through the streaming
+        // presigned-URL flow instead.
+        // The `as BlobPart` cast is only because the DOM lib types a Buffer's
+        // ArrayBufferLike (which could be a SharedArrayBuffer) too narrowly for
+        // BlobPart; the view is a valid Blob part at runtime.
+        const view = new Uint8Array(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+        form.append(fieldName, new Blob([view], { type: contentType(filePath) }), basename(filePath));
         for (const [key, value] of Object.entries(extra ?? {})) {
             form.append(key, value);
         }
@@ -389,6 +406,68 @@ export class LabelGridClient {
      * Bearer token would break the signature.
      */
     raw(url, init) {
-        return this.fetchFn(url, { signal: AbortSignal.timeout(this.rawTimeoutMs), ...init });
+        const timeoutSignal = AbortSignal.timeout(this.rawTimeoutMs);
+        // Compose, never replace: spreading `...init` last would let a caller-supplied
+        // signal silently drop the transfer timeout. AbortSignal.any aborts when
+        // EITHER the caller's signal or the timeout fires, so the timeout always holds.
+        const signal = init.signal != null ? AbortSignal.any([init.signal, timeoutSignal]) : timeoutSignal;
+        return this.fetchFn(url, { ...init, signal });
+    }
+    /**
+     * Authenticated raw GET for file-body downloads (statement CSV/PDF): sends the
+     * same auth headers as the JSON path but returns the live {@link Response} on
+     * success so the caller streams the body to disk, never buffering a large file
+     * in memory. A non-2xx is read and normalized to the same structured
+     * {@link ApiError} as the JSON path; a network/timeout failure maps to the same
+     * NETWORK_ERROR/TIMEOUT. Uses the longer raw transfer timeout, since a download
+     * is a byte transfer, not a JSON call.
+     */
+    async getRaw(path, query) {
+        const url = `${this.baseUrl}${path}${buildQuery(query)}`;
+        let res;
+        try {
+            res = await this.fetchFn(url, {
+                method: 'GET',
+                headers: this.authHeaders(),
+                signal: AbortSignal.timeout(this.rawTimeoutMs),
+            });
+        }
+        catch (err) {
+            return { ok: false, error: this.mapFetchError(err) };
+        }
+        if (res.ok)
+            return { ok: true, res };
+        // Read and normalize the error body exactly as the JSON path does.
+        let body = null;
+        try {
+            const text = await res.text();
+            if (text.length > 0) {
+                try {
+                    body = JSON.parse(text);
+                }
+                catch {
+                    body = text;
+                }
+            }
+        }
+        catch {
+            // no readable error body — normalizeError falls back to status defaults
+        }
+        return { ok: false, error: normalizeError(res, body) };
+    }
+    /** Maps a fetch rejection (abort/timeout vs other) to a structured error. */
+    mapFetchError(err) {
+        if (err instanceof DOMException && (err.name === 'TimeoutError' || err.name === 'AbortError')) {
+            return {
+                code: 'TIMEOUT',
+                message: `The request timed out after ${Math.round(this.rawTimeoutMs / 1000)} seconds. Try again, or narrow the request.`,
+                status: 0,
+            };
+        }
+        return {
+            code: 'NETWORK_ERROR',
+            message: err instanceof Error ? err.message : 'Network request failed.',
+            status: 0,
+        };
     }
 }

package/dist/api/upload.d.ts

@@ -13,8 +13,26 @@
  *
  * 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.
+ *
+ * The step-2 PUT streams the file from disk rather than buffering it whole: the
+ * request body is a read stream and the object's byte size is sent as an
+ * explicit Content-Length. (An S3-compatible presigned PUT rejects a chunked
+ * Transfer-Encoding body with 411 MissingContentLength, and fetch defaults a
+ * stream body to chunked, so the header is mandatory.) This keeps peak memory
+ * flat regardless of file size.
+ */
+import type { ApiError, ApiResult, LabelGridClient } from './http.js';
+/** Hard ceiling on a single uploaded file, in bytes (4 GiB). */
+export declare const MAX_UPLOAD_BYTES: number;
+/**
+ * Composes a byte-counting Transform onto `src` for progress reporting and —
+ * critically — forwards a SOURCE error onto the composed body. `pipe()` does NOT
+ * propagate a source-stream error to its destination, so without this a file
+ * that becomes unreadable mid-transfer (deleted, an I/O fault) would emit an
+ * unhandled 'error' on the read stream — crashing the process — instead of
+ * destroying the composed body so `fetch` rejects into the UPLOAD_FAILED catch.
  */
-import type { ApiResult, LabelGridClient } from './http.js';
+export declare function attachProgressCounter(src: NodeJS.ReadableStream, onProgress: (bytesSoFar: number) => void): NodeJS.ReadableStream;
 /**
  * The structural subset of {@link LabelGridClient} the presigned-upload flow
  * needs. Declared as a Pick so any object with these methods (including a test
@@ -28,5 +46,36 @@ export type UploadOptions = {
     commitPath: string;
     /** Absolute or relative local path to the file to upload. */
     filePath: string;
+    /** Byte ceiling override (defaults to {@link MAX_UPLOAD_BYTES}); for tests. */
+    maxBytes?: number;
+    /** Called with the running byte count as the upload streams (for a progress UI). */
+    onProgress?: (bytesSoFar: number) => void;
+};
+/**
+ * THE SEAM: the presigned flow is three independently-callable steps —
+ * {@link mintUpload} (get a signed URL + key), {@link putToPresignedUrl} (send
+ * the bytes), {@link commitUpload} (record the object) — and
+ * {@link uploadViaPresignedUrl} just composes them. An alternate transport that
+ * does the PUT out of process (e.g. a browser or a worker doing the byte
+ * transfer directly) can reuse mint + commit and swap only the middle step,
+ * without reimplementing the URL-minting or commit contracts.
+ */
+/** The result of minting a presigned URL: the signed URL + object key, or an error. */
+export type MintResult = {
+    uploadUrl: string;
+    key: string;
+} | {
+    error: ApiError;
 };
+/** Step 1: mint the presigned URL + object key for `filename`. */
+export declare function mintUpload(client: Pick<UploadHttp, 'post'>, uploadUrlPath: string, filename: string): Promise<MintResult>;
+/**
+ * Step 2: stream the file's bytes to the presigned URL — NO auth header (the URL
+ * is signed). Re-stats the file so Content-Length is its size at upload time,
+ * enforcing the byte ceiling and the FILE_NOT_FOUND (TOCTOU) contract there.
+ * Returns null on success, or a structured error.
+ */
+export declare function putToPresignedUrl(client: Pick<UploadHttp, 'raw'>, uploadUrl: string, filePath: string, maxBytes?: number, onProgress?: (bytesSoFar: number) => void): Promise<ApiError | null>;
+/** Step 3: commit the uploaded object key (idempotent — a retried commit will not duplicate). */
+export declare function commitUpload(client: Pick<UploadHttp, 'put'>, commitPath: string, key: string): Promise<ApiResult<unknown>>;
 export declare function uploadViaPresignedUrl(client: UploadHttp, opts: UploadOptions): Promise<ApiResult<unknown>>;

package/dist/api/upload.js

@@ -13,69 +13,118 @@
  *
  * 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.
+ *
+ * The step-2 PUT streams the file from disk rather than buffering it whole: the
+ * request body is a read stream and the object's byte size is sent as an
+ * explicit Content-Length. (An S3-compatible presigned PUT rejects a chunked
+ * Transfer-Encoding body with 411 MissingContentLength, and fetch defaults a
+ * stream body to chunked, so the header is mandatory.) This keeps peak memory
+ * flat regardless of file size.
  */
-import { statSync } from 'node:fs';
-import { readFile } from 'node:fs/promises';
+import { createReadStream, statSync } from 'node:fs';
 import { basename } from 'node:path';
+import { Transform } from 'node:stream';
 import { log } from '../log.js';
 import { contentType } from './content-types.js';
-/** True only for an existing regular file. */
-function isReadableFile(p) {
+/** Hard ceiling on a single uploaded file, in bytes (4 GiB). */
+export const MAX_UPLOAD_BYTES = 4 * 1024 * 1024 * 1024;
+/** Stats a path, returning its size only for an existing regular file. */
+function statReadableFile(p) {
     try {
-        return statSync(p).isFile();
+        const st = statSync(p);
+        return st.isFile() ? { size: st.size } : null;
     }
     catch {
-        return false;
+        return null;
     }
 }
-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),
+/**
+ * Composes a byte-counting Transform onto `src` for progress reporting and —
+ * critically — forwards a SOURCE error onto the composed body. `pipe()` does NOT
+ * propagate a source-stream error to its destination, so without this a file
+ * that becomes unreadable mid-transfer (deleted, an I/O fault) would emit an
+ * unhandled 'error' on the read stream — crashing the process — instead of
+ * destroying the composed body so `fetch` rejects into the UPLOAD_FAILED catch.
+ */
+export function attachProgressCounter(src, onProgress) {
+    let transferred = 0;
+    const counter = new Transform({
+        transform(chunk, _enc, cb) {
+            transferred += chunk.length;
+            onProgress(transferred);
+            cb(null, chunk);
+        },
     });
+    src.pipe(counter);
+    src.on('error', (e) => counter.destroy(e instanceof Error ? e : new Error(String(e))));
+    return counter;
+}
+function fileTooLargeError(size, limit) {
+    return {
+        code: 'FILE_TOO_LARGE',
+        message: `The file is ${size} bytes, over the ${limit}-byte upload limit.`,
+        status: 0,
+    };
+}
+/** Step 1: mint the presigned URL + object key for `filename`. */
+export async function mintUpload(client, uploadUrlPath, filename) {
+    const minted = await client.post(uploadUrlPath, { filename });
     if ('error' in minted)
-        return minted;
+        return { error: minted.error };
     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: {
+                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 = {
+    return { uploadUrl, key };
+}
+/**
+ * Step 2: stream the file's bytes to the presigned URL — NO auth header (the URL
+ * is signed). Re-stats the file so Content-Length is its size at upload time,
+ * enforcing the byte ceiling and the FILE_NOT_FOUND (TOCTOU) contract there.
+ * Returns null on success, or a structured error.
+ */
+export async function putToPresignedUrl(client, uploadUrl, filePath, maxBytes = MAX_UPLOAD_BYTES, onProgress) {
+    // The file may vanish between an earlier stat and this transfer (a TOCTOU
+    // race); a structured FILE_NOT_FOUND is the contract, not a throw.
+    const stat = statReadableFile(filePath);
+    if (stat === null) {
+        return {
             code: 'FILE_NOT_FOUND',
-            message: `The file at ${opts.filePath} could not be read.`,
+            message: `The file at ${filePath} could not be read.`,
             status: 0,
         };
-        return { error };
     }
+    if (stat.size > maxBytes)
+        return fileTooLargeError(stat.size, maxBytes);
     let putRes;
     try {
-        putRes = await client.raw(uploadUrl, {
+        // A stream body must declare Content-Length (a chunked PUT is rejected 411 by
+        // S3-compatible storage) and requires duplex: 'half' for undici's fetch.
+        let body = createReadStream(filePath);
+        if (onProgress !== undefined) {
+            // Count bytes as they pass through, inside the Transform (never a 'data'
+            // listener, which would flip the stream to flowing mode and race the
+            // reader). attachProgressCounter also forwards a source-stream error so a
+            // mid-transfer read failure becomes a clean UPLOAD_FAILED, not a crash.
+            body = attachProgressCounter(body, onProgress);
+        }
+        const putInit = {
             method: 'PUT',
-            headers: { 'Content-Type': contentType(opts.filePath) },
-            body: new Uint8Array(bytes),
-        });
+            headers: {
+                'Content-Type': contentType(filePath),
+                'Content-Length': String(stat.size),
+            },
+            body,
+            duplex: 'half',
+        };
+        putRes = await client.raw(uploadUrl, putInit);
     }
     catch (err) {
         // Never surface err.message raw to the log — it can embed the signed URL,
@@ -83,22 +132,45 @@ export async function uploadViaPresignedUrl(client, opts) {
         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 };
+        return { code: 'UPLOAD_FAILED', message: 'Uploading the file to storage failed.', status: 0 };
     }
     if (!putRes.ok) {
-        // Abort BEFORE the commit — a half-uploaded object is never finalized.
-        const error = {
+        return {
             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 });
+    return null;
+}
+/** Step 3: commit the uploaded object key (idempotent — a retried commit will not duplicate). */
+export function commitUpload(client, commitPath, key) {
+    return client.put(commitPath, { s3_key: key }, { idempotency: true });
+}
+export async function uploadViaPresignedUrl(client, opts) {
+    const limit = opts.maxBytes ?? MAX_UPLOAD_BYTES;
+    // Fail fast and locally: never touch the network for a file we cannot read,
+    // and reject an oversized file with an honest size error (not FILE_NOT_FOUND).
+    const initialStat = statReadableFile(opts.filePath);
+    if (initialStat === null) {
+        return {
+            error: {
+                code: 'FILE_NOT_FOUND',
+                message: `No readable file at ${opts.filePath}.`,
+                status: 0,
+            },
+        };
+    }
+    if (initialStat.size > limit) {
+        return { error: fileTooLargeError(initialStat.size, limit) };
+    }
+    // Compose the seam: mint → PUT the bytes → commit. A failed PUT aborts before
+    // the commit, so a half-uploaded object is never finalized.
+    const minted = await mintUpload(client, opts.uploadUrlPath, basename(opts.filePath));
+    if ('error' in minted)
+        return { error: minted.error };
+    const putError = await putToPresignedUrl(client, minted.uploadUrl, opts.filePath, limit, opts.onProgress);
+    if (putError !== null)
+        return { error: putError };
+    return commitUpload(client, opts.commitPath, minted.key);
 }

package/dist/entities.d.ts

@@ -7,7 +7,9 @@
  * 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 delete refusals). Caveats that belong to ONE tool stay in that tool's own
+ * description — the RELEASE_LOCKED_FIELDS rule lives on update_catalog_item, so
+ * repeating it here would only pad every client's catalog.
  */
 export type EntityName = 'label' | 'artist' | 'writer' | 'publisher' | 'release' | 'track';
 /** The entity names as a tuple, for zod enum inputs. */

package/dist/entities.js

@@ -7,45 +7,47 @@
  * 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 delete refusals). Caveats that belong to ONE tool stay in that tool's own
+ * description — the RELEASE_LOCKED_FIELDS rule lives on update_catalog_item, so
+ * repeating it here would only pad every client's catalog.
  */
 /** 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.',
+        filtersDoc: 'label: no documented filters.',
         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).',
+        filtersDoc: 'artist: 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).',
+        filtersDoc: 'writer: name, ipi.',
         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).',
+        filtersDoc: 'publisher: name, ipi.',
         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.',
+        filtersDoc: 'release: label_id, is_live (1 = live only), barcode_number (UPC/EAN), cat.',
+        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).',
         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).',
+        filtersDoc: 'track: release_id, 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.',
+        deleteNote: 'track: refused once the release is no longer an editable draft.',
     },
 };

package/dist/index.d.ts

@@ -11,3 +11,4 @@ export * from './api/http.js';
 export * from './api/upload.js';
 export * from './entities.js';
 export * from './log.js';
+export * from './timeouts.js';

package/dist/index.js

@@ -11,3 +11,4 @@ export * from './api/http.js';
 export * from './api/upload.js';
 export * from './entities.js';
 export * from './log.js';
+export * from './timeouts.js';

package/dist/timeouts.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Shared parsing for the configurable request/transfer timeouts, used by both
+ * the MCP server (env vars) and the CLI (flags and env vars). A value must be a
+ * positive integer number of milliseconds; anything else is rejected so the
+ * caller can fall back to the client default and warn once.
+ */
+export type TimeoutParse = {
+    /** The parsed positive-integer ms, or undefined when unset OR invalid. */
+    value: number | undefined;
+    /** True only when a value was supplied but was not a positive integer. */
+    invalid: boolean;
+};
+/** Parses a timeout string into a positive-integer millisecond value. */
+export declare function parseTimeoutMs(raw: string | undefined): TimeoutParse;

package/dist/timeouts.js

@@ -0,0 +1,15 @@
+/**
+ * Shared parsing for the configurable request/transfer timeouts, used by both
+ * the MCP server (env vars) and the CLI (flags and env vars). A value must be a
+ * positive integer number of milliseconds; anything else is rejected so the
+ * caller can fall back to the client default and warn once.
+ */
+/** Parses a timeout string into a positive-integer millisecond value. */
+export function parseTimeoutMs(raw) {
+    if (raw === undefined || raw.trim() === '')
+        return { value: undefined, invalid: false };
+    const n = Number(raw.trim());
+    if (Number.isInteger(n) && n > 0)
+        return { value: n, invalid: false };
+    return { value: undefined, invalid: true };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@labelgrid/core",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Shared LabelGrid public-API client: HTTP transport, uploads, content types, the catalog-entity registry, and redacting logging",
   "type": "module",
   "keywords": ["labelgrid", "music-distribution", "api-client"],