@etchv-labs/mcp-server 1.0.0 → 1.2.0

package/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+## 1.2.0
+
+- New `watermark_batch` tool: watermark up to 100 local files in one batch,
+  named by `input_paths`, `input_dir` with `glob`, or `items` with their own
+  data. `data_template` values may use `{filename}`, `{stem}` and `{index}`.
+  Files are uploaded to signed URLs without the API key, the batch is started,
+  and with `wait` it is polled at the pace the API asks for (`Retry-After`).
+  `wait_seconds` bounds the wait, progress notifications report uploads and
+  checks, and a canceled call stops waiting. A retry resumes the same batch
+  (sending only files not yet received); a batch that expired unstarted or
+  whose results expired is reported with a request for a new
+  `idempotency_key`. The 100-file cap is checked before anything is sent, and
+  globs cannot leave `input_dir` (braces and `..` are refused).
+  Directory listings filter by file type while walking and refuse a directory
+  too large to walk rather than return part of it. Uploads to signed URLs time
+  out (45 s plus time for the file at 128 KiB/s).
+- New `get_batch` tool to follow a batch, and `download_batch` to save each
+  successful result (named as in the batch zip) or the batch's zip and report failed items with their
+  error codes.
+
+## 1.1.0
+
+- `watermark_media` and `detect_media` send files over 40 MiB
+  (`ETCHV_LARGE_FILE_THRESHOLD`) through an upload session, without the API
+  key, and submit its `upload_id`.
+- Detection reads delivered files up to 192 MiB; image or PDF detection above
+  95 MiB returns a job receipt for `get_job_result`.

package/README.md

@@ -1,43 +1,37 @@
 # Etchv MCP server
 
-[![npm](https://img.shields.io/npm/v/@etchv-labs/mcp-server)](https://www.npmjs.com/package/@etchv-labs/mcp-server)
-[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+A local stdio [Model Context Protocol](https://modelcontextprotocol.io) server
+that lets AI assistants watermark and detect images, PDFs and videos with
+[Etchv](https://etchv.com).
 
-Let an AI assistant watermark and inspect images, PDFs and videos with the
-[Etchv API](https://etchv.com/docs). Supports synchronous results and asynchronous
-jobs, asset management, customer storage destinations and webhook deliveries.
+## Requirements
 
-This is a local **stdio** [Model Context Protocol](https://modelcontextprotocol.io)
-server. It connects to the hosted Etchv API with your organization's scoped API
-key. There is no hosted MCP URL to configure. Node.js 24 or later is required.
+- Node.js 24 or later
+- An Etchv API key with only the [scopes](#tools) you need
+- An existing directory for input and output files
 
 ## Configuration
 
 | Variable | Required | Description |
 | --- | --- | --- |
-| `ETCHV_API_KEY` | Yes | Etchv API key. Grant only the [scopes](#tools-and-key-scopes) you need. |
+| `ETCHV_API_KEY` | Yes | Etchv API key. Keep it in your client's secret or env config, never in chat. |
 | `ETCHV_FILES_ROOT` | Yes | Absolute path of an existing directory. All input and output files must be inside it. |
 | `ETCHV_API_BASE_URL` | No | API origin. Defaults to `https://api.etchv.com`. |
-
-Create the media directory first. Store the API key in your client's secret or
-environment configuration; do not paste it into a conversation or commit it.
-The examples pin the major version with `@etchv-labs/mcp-server@1`.
+| `ETCHV_LARGE_FILE_THRESHOLD` | No | Files above this many bytes are uploaded once to a signed URL and sent by ID. Defaults to 40 MiB. |
 
 ### Claude Code
 
 ```sh
-export ETCHV_API_KEY=...   # or load it from your secret manager
 claude mcp add etchv --scope user \
   -e ETCHV_API_KEY="$ETCHV_API_KEY" \
   -e ETCHV_FILES_ROOT="$HOME/etchv-media" \
   -- npx -y @etchv-labs/mcp-server@1
 ```
 
-### Claude Desktop, Cursor, Windsurf and other `mcpServers` clients
+### Claude Desktop, Cursor and other `mcpServers` clients
 
-Add this entry to the client's MCP configuration (for Claude Desktop,
-`claude_desktop_config.json`; for Cursor, `~/.cursor/mcp.json`), then restart
-the client:
+Add this to the client's MCP config (for example `claude_desktop_config.json`
+or `~/.cursor/mcp.json`) and restart it:
 
 ```json
 {
@@ -54,229 +48,79 @@ the client:
 }
 ```
 
-If the client does not inherit your shell `PATH`, use the absolute path of `npx`.
-
-### VS Code
-
-Add to `.vscode/mcp.json`. VS Code prompts for the key and stores it securely:
-
-```json
-{
-  "inputs": [
-    {
-      "type": "promptString",
-      "id": "etchv-api-key",
-      "description": "Etchv API key",
-      "password": true
-    }
-  ],
-  "servers": {
-    "etchv": {
-      "type": "stdio",
-      "command": "npx",
-      "args": ["-y", "@etchv-labs/mcp-server@1"],
-      "env": {
-        "ETCHV_API_KEY": "${input:etchv-api-key}",
-        "ETCHV_FILES_ROOT": "/absolute/path/to/etchv-media"
-      }
-    }
-  }
-}
-```
-
-### Global install
-
-`npm install -g @etchv-labs/mcp-server@1` installs the `etchv-mcp` command. Use
-`etchv-mcp` as the configured command with the same environment variables.
-
-Ask the assistant to run `check_api_key` to confirm the connection. It returns
-your organization ID, key ID and granted scopes without spending credits.
-
-## Try it
-
-Put `photo.jpg` inside your configured media directory, then ask your assistant:
-
-> Watermark photo.jpg for recipient delivery-42 using Etchv. Use an async job,
-> collect the result as photo-watermarked.jpg, then detect its watermark.
-
-The assistant can read `etchv://capabilities` for format and workflow guidance.
-To watermark directly, call `watermark_media` with:
-
-```json
-{
-  "media": "images",
-  "input_path": "photo.jpg",
-  "data": { "recipient": "delivery-42" },
-  "mode": "async",
-  "idempotency_key": "delivery-42-photo-v1"
-}
-```
-
-The result includes `request_id`. Check `get_job` with `operation: "embed"`, then
-call `get_job_result` with that request ID, operation and
-`output_path: "photo-watermarked.jpg"`. Pending results return a 202 receipt;
-call again later. Use the same pattern with `operation: "detect"` for an async
-detection result. Detection returns JSON and does not accept an output path.
-
-For **sync**, set `mode: "sync"` and provide `output_path` when watermarking.
-The API waits for a bounded period. It can still return a 202 receipt if processing
-continues; collect it through the job tools. Async is the MCP default for every
-media type. There is no automatic polling or background retry loop in the server.
-
-Every submission requires a stable `idempotency_key`. Reuse it for the same input,
-data and options after an uncertain failure. Do not generate another key on a
-retry: that can create another billable operation. Results include the key and,
-when supplied by the API, a request ID. A client cancellation or timeout does not
-cancel an accepted API job. API failures set MCP `isError` with an HTTP status and
-safe message; retry delays are returned when available.
-
-## Formats and credits
-
-| Media value | Formats | Preservation |
-| --- | --- | --- |
-| `images` | JPEG, PNG, APNG, TIFF, PSD, PSB, GIF, BMP, PPM, WebP | Original format, supported animation, pages and layers |
-| `documents` | PDF | Selectable text and vector content |
-| `videos` | MP4, MOV with supported H.264 encoding | Container and supported audio; audio is not watermarked |
-
-Format availability follows your plan. The server does not bypass API validation
-or media limits. Uploads are limited to 20 MiB and MCP file downloads to 512 MiB.
-Watermarking uses one credit per image or PDF file, or per started video minute.
-Detection also uses API credits. See [limits](https://etchv.com/docs/api/errors).
-
-Watermarks encode the digest of the provided JSON. Detection recovers that digest,
-not the original data. Test your compression and transformation workflow before
-relying on detection; a recovered identifier is not proof of who shared a file.
-
-## Tools and key scopes
-
-| Tools | Required scope |
-| --- | --- |
-| `check_api_key` | Any valid key |
-| `watermark_media` | `watermarks:embed` |
-| `detect_media` | `watermarks:detect` |
-| `get_job`, `get_job_result` | Corresponding embed or detect scope |
-| `list_assets`, `get_asset`, `download_asset` | `assets:read` |
-| `update_asset` | `assets:write` |
-| `delete_asset` | `assets:delete`, owner/admin |
-| `list_storage_destinations`, `list_storage_deliveries`, `get_storage_delivery` | `storage:read` |
-| `verify_storage_destination`, `store_asset`, `retry_storage_delivery` | `storage:write`, owner/admin |
-| `list_webhooks`, `list_webhook_deliveries` | `webhooks:read` |
-| `redeliver_webhook` | `webhooks:write`, owner/admin |
-
-Give the key only the scopes you need. Your MCP client's approval settings govern
-billable and destructive tools; MCP annotations describe their effects. The API
-always enforces organization isolation, scopes, roles and plan access.
-
-Asset listing supports cursor pagination and media/kind/watermark filters.
-Updates require the current asset `version` to prevent lost edits; `metadata`
-replaces the whole object, and null clears it. Downloads create new local files
-and return paths, byte counts and SHA-256 hashes, never media bytes in chat.
-
-## Storage and webhooks
-
-Etchv stores uploads and watermarked results automatically. Job results remain
-available for 24 hours; Etchv asset downloads for 30 days, with asset records
-retained until deleted. No customer bucket is required.
-
-Alternatively, configure and verify your own S3, Google Cloud Storage or Azure
-Blob Storage destination in the dashboard. Select its `storage_destination_id`
-on `watermark_media`, optionally with a relative `storage_key`. The watermarked
-result is stored in that bucket instead, and its retention is yours to control.
-Use `store_asset` to choose a destination for an existing watermarked asset.
-After successful delivery, Etchv removes its staged output; asset downloads read
-from your bucket. Deleting an asset does not delete objects in your bucket.
-
-Configure webhook endpoints and retain their signing secrets through the
-dashboard. Pass an existing `webhook_id` on an **async** submission, then inspect
-or redeliver events with the webhook tools. Redelivery may trigger your receiver's
-automation again. Credential and endpoint creation is deliberately handled in the
-dashboard; this server does not accept cloud credentials or return signing secrets.
-
-## File access and runtime
-
-`ETCHV_FILES_ROOT` is required and must name an existing absolute directory. Paths
-may be relative to it or absolute within it. Symlink paths and traversal outside
-the root are rejected. Output parents must already exist; existing files are never
-overwritten. Use a dedicated directory that is not modified by untrusted local
-processes while the server runs. This is an application-level boundary, not an OS
-sandbox. Upload only files you intend to send to Etchv.
-
-API responses must start within 45 seconds; file downloads have a 10-minute
-deadline. At most four tool calls run concurrently.
-Redirects are never followed. Optional `ETCHV_API_BASE_URL` must be an HTTPS origin;
-HTTP is accepted only for localhost development. Never point it at an untrusted
-host: it receives your key and uploads. stdout is reserved for MCP protocol traffic.
-Asset metadata and other API content are data, never instructions to an assistant.
+Then ask the assistant to run `check_api_key` to confirm the connection.
 
 ## Tools
 
-| Tool | Effect |
-| --- | --- |
-| `check_api_key` | Read-only connection check: organization ID, key ID and scopes. No credits. |
-| `watermark_media` | Upload a local file and watermark it (sync or async). Spends credits. |
-| `detect_media` | Upload a local file and detect a watermark (sync or async). Uses credits. |
-| `get_job` | Read-only job status for an embed or detect job. |
-| `get_job_result` | Collect a finished job; embedding results are saved to a new local file. |
-| `list_assets`, `get_asset` | Read-only asset listing and records. |
-| `download_asset` | Save an asset to a new local file. |
-| `update_asset` | Rename an asset or replace its metadata (version-checked). |
-| `delete_asset` | Delete an asset. Destructive. |
-| `list_storage_destinations`, `list_storage_deliveries`, `get_storage_delivery` | Read-only storage inspection. |
-| `verify_storage_destination`, `store_asset`, `retry_storage_delivery` | Use a configured customer bucket. |
-| `list_webhooks`, `list_webhook_deliveries` | Read-only webhook inspection. |
-| `redeliver_webhook` | Resend an existing event to its endpoint. |
-
-Each tool declares MCP annotations (`readOnlyHint`, `destructiveHint`,
-`idempotentHint`, `openWorldHint`) so clients can require approval for billable,
-destructive or other write operations. The `etchv://capabilities` resource
-describes formats, modes, billing and file handling for the assistant.
+| Tool | What it does | Key scope |
+| --- | --- | --- |
+| `check_api_key` | Show organization ID, key ID and scopes; no credits | Any valid key |
+| `watermark_media` | Watermark a local file, sync or async; spends credits | `watermarks:embed` |
+| `detect_media` | Detect a watermark, sync or async; uses credits | `watermarks:detect` |
+| `get_job`, `get_job_result` | Read job status; collect a finished result | Matching embed/detect scope |
+| `watermark_batch` | Watermark up to 100 local files in one batch, each with its own data; spends credits | `watermarks:embed` |
+| `get_batch`, `download_batch` | Follow a batch; save each result or the batch's zip | `watermarks:embed` |
+| `list_assets`, `get_asset`, `download_asset` | List, inspect and download assets | `assets:read` |
+| `update_asset` | Rename or replace metadata (version-checked) | `assets:write` |
+| `delete_asset` | Delete an asset | `assets:delete`, owner/admin |
+| `list_storage_destinations`, `list_storage_deliveries`, `get_storage_delivery` | Inspect customer storage | `storage:read` |
+| `verify_storage_destination`, `store_asset`, `retry_storage_delivery` | Test a bucket; deliver or retry a result | `storage:write`, owner/admin |
+| `list_webhooks`, `list_webhook_deliveries` | Inspect webhook endpoints and deliveries | `webhooks:read` |
+| `redeliver_webhook` | Resend an existing event | `webhooks:write`, owner/admin |
+
+Submissions require a stable `idempotency_key`; reuse it when retrying so you
+are not charged twice. Image uploads are limited to 50 MiB and PDF and video
+uploads to 20 MiB. Detection takes the files Etchv delivered: up to 192 MiB for
+images, 64 MiB for PDFs and 100 MiB for video. Files over 40 MiB go through an
+upload session automatically, and image or PDF detection above 95 MiB returns a
+job receipt to collect with `get_job_result`. Storage destinations and webhook endpoints are created in the
+dashboard, not through this server.
+
+`watermark_media` and `detect_media` accept an optional `accelerator` (`cpu`,
+the default, or `gpu`). GPU processing requires a Business or Enterprise plan
+and costs 3× credits; if no GPU is ready, the job runs on CPU at normal credits.
+Results report the hardware actually used as `accelerator`, and `get_job` also
+returns `accelerator_requested`. When a rate or concurrency limit is reached,
+errors include `retry_after_seconds` and point to the plan upgrade page. Trial and
+Launch plans run one operation at a time.
+
+### Batches
+
+`watermark_batch` takes up to 100 files, named one of three ways: `input_paths`,
+`input_dir` with an optional `glob` (for example `"contracts/*.pdf"`; braces and `..` are refused), or
+`items` with their own `data`. A `data_template` fills in each file's data;
+string values may use `{filename}`, `{stem}` and `{index}` (the file's 0-based
+position). The server creates the batch, uploads each file once to its signed
+URL without the API key, and starts it. With `wait: true` it polls at the pace
+the API asks for, for up to `wait_seconds` (default 600), sending progress
+notifications when the client asks for them, and with `output_dir` saves the
+results. Otherwise call `get_batch`, then `download_batch`, which saves each
+successful file under its name in the batch zip (`NNN-<name>-watermarked.<ext>`), or the single zip when the
+batch was created with `archive: true`, and lists failed items with their error
+codes. Each file costs the same credits as a single request, and files that
+fail are refunded. Retrying with the same arguments resumes or returns the
+same batch; if that batch expired unstarted or its results have expired, the
+tool asks for a new `idempotency_key`.
 
 ## Security
 
-- The API key is read only from `ETCHV_API_KEY`. It is sent only to the configured
-  API origin in the `X-API-Key` header and never appears in tool arguments,
-  results, errors or logs. Tools never accept or return cloud credentials or
-  webhook signing secrets; manage those in the dashboard.
-- stdout carries only MCP protocol messages. Startup errors go to stderr as fixed
-  messages without secrets.
+- The API key is read only from `ETCHV_API_KEY`, sent only to the configured
+  origin, and never appears in tool arguments, results, errors or logs.
 - File access is confined to `ETCHV_FILES_ROOT`: traversal and symlinks are
-  rejected, outputs are created exclusively with mode `0600` and never overwrite
-  existing files, and partial downloads are removed.
-- Redirects are never followed, and only HTTPS origins are accepted (HTTP only
-  for localhost development).
-- API responses, asset names and metadata are untrusted data, never instructions.
+  rejected, and existing files are never overwritten.
+- Only HTTPS origins are accepted (HTTP for localhost only), and redirects are
+  never followed.
+- API responses, asset names and metadata are treated as untrusted data, never
+  instructions.
 
-## Development
-
-```sh
-npm ci
-npm run lint
-npm run typecheck
-npm test
-npm run build
-```
-
-Native TypeScript tests exercise the compiled server over stdio with the official
-MCP client, covering all media routes, file fidelity, job continuation, storage,
-webhooks, pagination, error handling, timeouts and file access. CI runs on Node 24
-on Linux, macOS and Windows. The optional live suite uses small synthetic media
-fixtures:
-
-```sh
-# Set ETCHV_INTEGRATION_API_KEY securely; requires embed, detect, assets:read,
-# assets:delete and owner/admin for cleanup. Uses real API credits.
-npm run test:live
-```
+## Links
 
-Without a key, live tests are skipped. Etchv's private CI requires that key and
-runs real JPEG, PDF and MP4 embed/detect roundtrips in both modes before publishing.
-It checks idempotent async replay and asset downloads, and deletes created assets.
+- Guide: https://etchv.com/docs/mcp
+- API reference: https://etchv.com/docs
+- Issues: https://github.com/etchv-labs/mcp-server/issues
+- Support: hello@etchv.com
 
-This public repository is an MIT-licensed source snapshot of `mcp/` in Etchv's
-monorepo, with independent history. Contributions are reviewed and incorporated
-there before publication. Private service code, credentials and customer fixtures
-are not included. Report issues at
-[github.com/etchv-labs/mcp-server/issues](https://github.com/etchv-labs/mcp-server/issues).
+Questions or bug reports: open an issue here or email hello@etchv.com.
 
 ## License
 

package/dist/api.js

@@ -11,24 +11,25 @@ const messages = {
     413: "The upload exceeds API limits.",
     415: "Media format or encoding is unsupported.",
     422: "The API rejected the file or request fields. Check the format limits in the documentation.",
-    429: "Rate limit reached. Retry after the indicated delay.",
+    429: "Plan rate or concurrency limit reached. Retry after the indicated delay, or upgrade at https://etchv.com/dashboard/billing to run more operations at once.",
 };
 export class ApiError extends SafeError {
     status;
     request_id;
     retry_after_seconds;
-    constructor(response) {
-        super(messages[response.status] ||
-            `Etchv request failed (HTTP ${response.status}).`);
+    constructor(response, gpuRequested = false) {
+        super(response.status === 403 && gpuRequested
+            ? `${messages[403]} GPU processing requires Business or a higher plan.`
+            : messages[response.status] ||
+                `Etchv request failed (HTTP ${response.status}).`);
         this.status = response.status;
         const id = response.headers.get("x-request-id");
         this.request_id = /^req_[a-f0-9]{64}$/.test(id ?? "") ? id : undefined;
-        const retry = response.headers.get("retry-after");
-        this.retry_after_seconds = /^\d{1,6}$/.test(retry ?? "")
-            ? Number(retry)
-            : undefined;
+        this.retry_after_seconds = retryAfter(response);
     }
 }
+/** Slowest upload rate a signed PUT is given time for, in bytes per second. */
+export const UPLOAD_FLOOR = 128 * 1024;
 export function apiClient({ apiKey, baseUrl = "https://api.etchv.com", timeout = 45000, bodyTimeout = 600000, }) {
     if (!apiKey || /[\r\n]/.test(apiKey))
         throw new SafeError("Set ETCHV_API_KEY to an Etchv API key.");
@@ -90,12 +91,94 @@ export function apiClient({ apiKey, baseUrl = "https://api.etchv.com", timeout =
             timer.unref();
             if (!response.ok) {
                 await response.body?.cancel();
-                throw new ApiError(response);
+                throw new ApiError(response, url.searchParams.get("accelerator") === "gpu");
             }
             return response;
         },
+        /**
+         * Upload a file once through an upload session and return its upload_id, to
+         * send instead of the file. The signed URL carries its own authorization, so
+         * the API key never goes to it.
+         */
+        async upload(kind, bytes, filename, signal) {
+            const session = await jsonResponse(await this.request("/uploads", {
+                method: "POST",
+                body: { kind, filename, size: bytes.length },
+                signal,
+            }));
+            if (!/^upl_[a-f0-9]{32}$/.test(String(session.upload_id)))
+                throw new SafeError("API returned an invalid upload session.");
+            await this.put(session.upload, bytes, signal);
+            return String(session.upload_id);
+        },
+        /**
+         * PUT bytes to a signed upload URL from the API (an upload session or a
+         * batch item). Only the signature in the URL authorizes it: the API key is
+         * never sent there.
+         */
+        async put(upload, bytes, signal) {
+            const { method, url } = (upload ?? {});
+            let target;
+            try {
+                target = new URL(String(url));
+            }
+            catch {
+                throw new SafeError("API returned an invalid upload session.");
+            }
+            const local = base.protocol === "http:" &&
+                target.protocol === "http:" &&
+                ["localhost", "127.0.0.1", "[::1]"].includes(target.hostname);
+            if (method !== "PUT" ||
+                target.username ||
+                target.password ||
+                (target.protocol !== "https:" && !local))
+                throw new SafeError("API returned an invalid upload session.");
+            // Each attempt gets the request deadline plus time for the body at a
+            // floor of 128 KiB/s, so a stalled upload cannot hang the call.
+            const deadline = timeout + Math.ceil((bytes.length / UPLOAD_FLOOR) * 1000);
+            for (let attempt = 0;; attempt++) {
+                let response;
+                try {
+                    response = await fetch(target, {
+                        method: "PUT",
+                        body: new Blob([bytes]),
+                        headers: {
+                            "Content-Type": "application/octet-stream",
+                            "User-Agent": USER_AGENT,
+                        },
+                        redirect: "manual",
+                        signal: AbortSignal.any([
+                            AbortSignal.timeout(deadline),
+                            ...(signal ? [signal] : []),
+                        ]),
+                    });
+                }
+                catch (error) {
+                    if (signal?.aborted)
+                        throw error;
+                    if (attempt < 2)
+                        continue;
+                    if (error instanceof Error && error.name === "TimeoutError")
+                        throw new SafeError("The file upload timed out. Check the network connection.");
+                    throw error;
+                }
+                await response.body?.cancel();
+                if (response.status === 200)
+                    return;
+                if (response.status >= 500 && attempt < 2)
+                    continue;
+                throw new SafeError(response.status === 413
+                    ? "The file exceeds the upload limit for this operation."
+                    : `The upload was refused (HTTP ${response.status}).`);
+            }
+        },
     };
 }
+/** Seconds from a Retry-After header, when it holds a plain number. */
+export function retryAfter(response) {
+    const value = response.headers.get("retry-after");
+    return /^\d{1,6}$/.test(value ?? "") ? Number(value) : undefined;
+}
 export async function jsonResponse(response) {
     if (response.status === 204)
         return { success: true };

package/dist/batches.js

@@ -0,0 +1,110 @@
+import { basename, extname } from "node:path";
+import { SafeError } from "./io.js";
+/** Files per batch, as the API enforces. */
+export const MAX_BATCH_ITEMS = 100;
+const MIB = 1024 * 1024;
+/** Batch file types by extension, with the API's per-kind size caps. */
+const KINDS = {
+    ".jpg": "image",
+    ".jpeg": "image",
+    ".png": "image",
+    ".tif": "image",
+    ".tiff": "image",
+    ".psd": "image",
+    ".psb": "image",
+    ".gif": "image",
+    ".bmp": "image",
+    ".ppm": "image",
+    ".webp": "image",
+    ".pdf": "document",
+    ".mp4": "video",
+    ".mov": "video",
+};
+const LIMITS = { image: 50 * MIB, document: 20 * MIB, video: 20 * MIB };
+/** States after which a batch makes no further progress. */
+export const BATCH_DONE = new Set([
+    "completed",
+    "failed",
+    "cancelled",
+    "expired",
+]);
+export const isBatchFile = (path) => extname(path).toLowerCase() in KINDS;
+/** Upload size cap for a batch file, or an error naming the file. */
+export function batchLimit(path) {
+    const kind = KINDS[extname(path).toLowerCase()];
+    if (!kind)
+        throw new SafeError(`${path}: unsupported file type. Batches take images, PDFs and MP4 or MOV videos.`);
+    return LIMITS[kind];
+}
+/** Replace {filename}, {stem} and {index} in every string value. */
+export function fillTemplate(value, vars) {
+    if (typeof value === "string")
+        return value.replace(/\{(filename|stem|index)\}/g, (_, name) => vars[name]);
+    if (Array.isArray(value))
+        return value.map((v) => fillTemplate(v, vars));
+    if (value && typeof value === "object")
+        return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, fillTemplate(v, vars)]));
+    return value;
+}
+export function checkData(data, label) {
+    if (!data ||
+        typeof data !== "object" ||
+        Array.isArray(data) ||
+        !Object.keys(data).length ||
+        Buffer.byteLength(JSON.stringify(data)) > 8192)
+        throw new SafeError(`${label}: data must be a non-empty JSON object up to 8 KiB.`);
+    return data;
+}
+export const stemOf = (filename) => basename(filename, extname(filename));
+/** The API's file stem rule: other characters become -, trimmed, 180 at most. */
+export function safeStem(filename) {
+    const name = filename.split(/[\\/]/).pop() ?? "";
+    const stem = name.slice(0, name.length - extname(name).length);
+    return (stem
+        .replace(/[^A-Za-z0-9._-]+/g, "-")
+        .replace(/^[-.]+|[-.]+$/g, "")
+        .slice(0, 180) || "image");
+}
+/**
+ * Local name for a downloaded item, the same as its entry in the batch zip:
+ * NNN- plus the result's own file name (from Content-Disposition), or the
+ * name the API derives from the uploaded file when the header has none.
+ */
+export function outputName(index, filename, disposition) {
+    const prefix = `${String(index).padStart(3, "0")}-`;
+    const given = /filename="([A-Za-z0-9._-]{1,240})"/.exec(disposition ?? "")?.[1];
+    if (given && !given.startsWith("."))
+        return prefix + given;
+    const ext = extname(filename.split(/[\\/]/).pop() ?? "")
+        .toLowerCase()
+        .replace(/[^a-z0-9.]/g, "");
+    return `${prefix}${safeStem(filename)}-watermarked${ext}`;
+}
+/** The batch without signed upload URLs, which are credentials. */
+export function publicBatch(view) {
+    const items = Array.isArray(view.items) ? view.items : undefined;
+    return {
+        ...view,
+        ...(items
+            ? {
+                items: items.map(({ upload, ...item }) => ({
+                    ...item,
+                    ...(upload ? { awaiting_upload: true } : {}),
+                })),
+            }
+            : {}),
+    };
+}
+/** Items of a finished batch that did not succeed, with their error codes. */
+export function failedItems(view) {
+    const items = Array.isArray(view.items) ? view.items : [];
+    return items
+        .filter((item) => item.status !== "succeeded")
+        .map(({ index, filename, status, error_code, error_detail }) => ({
+        index,
+        filename,
+        status,
+        error_code,
+        error_detail,
+    }));
+}

package/dist/cli.js

@@ -7,6 +7,7 @@ try {
         apiKey: process.env.ETCHV_API_KEY,
         baseUrl: process.env.ETCHV_API_BASE_URL,
         filesRoot: process.env.ETCHV_FILES_ROOT,
+        largeFileThreshold: process.env.ETCHV_LARGE_FILE_THRESHOLD,
     };
     // Validate before accepting a connection. stdout is reserved for MCP messages.
     const initial = await createServer(config);