@bedolla/enrivision 0.1.5 → 0.1.6

package/README.md

@@ -11,7 +11,7 @@ This is useful for media types that many MCP clients cannot read reliably (video
 
 ## Requirements
 
-- Node.js `>= 22` (recommended: Node 24 LTS)
+- Node.js `>= 24`
 - A reachable EnriProxy server with these endpoints enabled:
   - `POST /v1/uploads`
   - `HEAD /v1/uploads/:id`
@@ -85,7 +85,7 @@ Example: no install (always uses whatever npm currently tags as `latest`)
   "EnriVision": {
     "type": "stdio",
     "command": "node",
-    "args": ["C:\\\\Users\\\\Administrator\\\\Projects\\\\EnriVision\\\\dist\\\\index.js"],
+    "args": ["C:\\Users\\Administrator\\Projects\\EnriVision\\dist\\index.js"],
     "env": {
       "ENRIPROXY_URL": "http://127.0.0.1:8787",
       "ENRIPROXY_API_KEY": "YOUR_ENRIPROXY_API_KEY",
@@ -104,9 +104,34 @@ EnriVision is configured via environment variables:
 - `ENRIPROXY_URL` (`string`, optional, default: `http://127.0.0.1:8787`)
 - `ENRIPROXY_API_KEY` (`string`, required)
 - `ENRIVISION_TIMEOUT_MS` (`string`, optional, default: `1800000`)
-  - Parsed as an integer (milliseconds). Uploads are performed in chunks; this timeout applies per request.
+  - Parsed as an integer (milliseconds). This is the operator cap: the per-call analyze timeout is `min(operator, mode budget)` with `single` = 10 min (one pass, fast/cheap), `multipass`/`auto` = 20 min (per-segment/batch map + reduce; `auto` may escalate to multipass server-side). Uploads are performed in chunks; per-chunk timeouts honor `min(operator, derived 30s..300s)` floored at 30 s (an operator budget below 30 s never forces tighter single-chunk budgets).
 - `ENRIVISION_DEFAULT_LANGUAGE` (`string`, optional)
   - Default language to send when the tool call does not provide `language`.
+- `ENRIVISION_DENY_SYMLINKS` (`string`, optional)
+  - Set to `1` to reject symlinked `path`/`paths` inputs. Strict mode opens with `O_NOFOLLOW` (POSIX) and compares the `dev:ino` handle identity from `fstat`. On Windows (`win32`) `O_NOFOLLOW` is `0` (advisory only), so strict mode there rests solely on the `lstat`-vs-`fstat` comparison with a small swap window: prefer POSIX hosts when symlink races are in scope.
+- `ENRIVISION_MODEL` (`string`, optional)
+  - Model id for server-side dispatch affinity; omit for auto-dispatch.
+- `ENRIVISION_QUIET` (`string`, optional)
+  - Set to `1` to silence upload/retry progress lines on stderr.
+
+## Analysis budgets
+
+The client analyze timeout is `min(ENRIVISION_TIMEOUT_MS, mode budget)`:
+
+- `single` → 10 min (mirrors EnriCode and the EnriProxy single-pass stage budget).
+- `multipass` → 20 min (mirrors EnriCode and the server multipass wall-clock budget).
+- `auto` (default) → 20 min: the server picks the mode and may escalate to multipass, so the client cannot assume the short budget. If unsure, omit tuning (`auto`).
+
+## Error shape
+
+Tool failures return MCP `isError` with Spanish-first bilingual text (ES first, EN second) plus machine-readable `structuredContent: { code, retryable, httpStatus? }` reusing the EnriCode vocabulary:
+
+- `ENRICODE_ERR_TOOL_INPUT_INVALID` — argument/tuning errors (including proxy 400/422). Never retry unchanged (`retryable: false`).
+- `ENRICODE_ERR_TOOL_EXECUTION_FAILED` — server/transport failures. `retryable` is true for 408/429/5xx, false otherwise.
+- `ENRICODE_ERR_TOOL_EXECUTION_TIMEOUT` — expired upload/analyze budgets (`retryable: true`; retry with a smaller scope).
+- `ENRICODE_ERR_TOOL_EXECUTION_ABORTED` — caller-cancelled (`retryable: false`).
+
+`httpStatus` is present only when the failure carries a proxy HTTP status.
 
 ## MCP tools
 
@@ -120,7 +145,7 @@ EnriVision exposes this MCP tool:
 General notes:
 
 - The tool accepts a single JSON object as its input (the MCP `arguments`).
-- Exactly one of `path` or `paths` is required.
+- At least one of `path` or `paths` is required. When `paths` carries at least one valid entry, `path` is ignored (explicit ignore-path contract: sending both is allowed, `path` is silently ignored — prefer oneOf semantics and send only one).
 - Paths must be absolute on the machine running the MCP server, or http(s) URLs. URLs are downloaded to a temporary directory on the MCP host (up to 64 MiB each; localhost and private-network destinations are blocked) and deleted after analysis.
 - EnriVision does not accept per-call `server_url`/`api_key` overrides (these are configured via env vars).
 
@@ -135,7 +160,7 @@ Inputs:
 - `language` (`string`, optional): preferred response language (ISO 639-1; e.g., `es`, `en`). If omitted, uses `ENRIVISION_DEFAULT_LANGUAGE` when set.
 - `analysis_mode` (`string`, optional): `auto` | `single` | `multipass`.
 - `max_frames` (`number`, optional): single-pass video frames (`1..20`).
-- `transcribe` (`boolean`, optional): enable/disable transcription (videos).
+- `transcribe` (`boolean`, optional): enable/disable transcription (videos). Has no effect on images/documents (declared in `warnings`, ignored).
 - `transcription_language` (`string`, optional): whisper hint (`auto`, `es`, `en`, ...).
 
 Video targeting:
@@ -169,7 +194,7 @@ Example `arguments` object:
 
 ```jsonc
 {
-  "path": "C:\\\\path\\\\to\\\\video.mp4",
+  "path": "C:\\path\\to\\video.mp4",
   "question": "What are the key steps demonstrated?",
   "analysis_mode": "auto",
   "transcribe": true,

package/dist/client/EnriProxyClient.d.ts

@@ -9,95 +9,35 @@
  *
  * @module client/EnriProxyClient
  */
+import { type AnalyzeVisionParams, type AnalyzeVisionResponse, type AppendUploadChunkParams, type CreateUploadSessionParams, type CreateUploadSessionResponse, type EnriProxyClientConfig, type FetchSegmentPageParams, type SegmentPageResponse } from "./EnriProxyClientContract.js";
+export { EnriProxyHttpError } from "./EnriProxyClientContract.js";
+export type { AnalyzeVisionElement, AnalyzeVisionParams, AnalyzeVisionResponse, AppendUploadChunkParams, CreateUploadSessionParams, CreateUploadSessionResponse, FetchSegmentPageParams, EnriProxyAudioTuning, EnriProxyClientConfig, EnriProxyDocumentTuning, EnriProxyHttpResult, EnriProxyImageRegion, EnriProxyImagesTuning, EnriProxyVideoTuning, SegmentPageResponse, } from "./EnriProxyClientContract.js";
 /**
- * Connection configuration for {@link EnriProxyClient}.
+ * Timeout for upload session creation (`POST /v1/uploads`, 60 s).
+ *
+ * @remarks
+ * Mirrors EnriCode `VisionAnalyzeMediaUploadCoordinator` (60 s create
+ * budget): session creation is a tiny metadata call, but it deserves more
+ * headroom than offset probes. Capped by the operator timeout via `Math.min`.
  */
-export interface EnriProxyClientConfig {
-    /**
-     * EnriProxy base URL (e.g., https://proxy.example.com).
-     */
-    readonly baseUrl: string;
-    /**
-     * EnriProxy API key (sent as Authorization: Bearer ...).
-     */
-    readonly apiKey: string;
-    /**
-     * Default request timeout in milliseconds.
-     */
-    readonly timeoutMs: number;
-}
+export declare const CREATE_CONTROL_TIMEOUT_MS: number;
 /**
- * Response from POST `/v1/uploads`.
- */
-export interface CreateUploadSessionResponse {
-    /**
-     * Upload session identifier.
-     */
-    readonly upload_id: string;
-    /**
-     * Recommended chunk size in bytes.
-     */
-    readonly chunk_size_bytes: number;
-    /**
-     * Expiration timestamp in ms since epoch.
-     */
-    readonly expires_at: number;
-}
-/**
- * Response from POST `/v1/vision/analyze`.
+ * Timeout for upload offset probes (`HEAD /v1/uploads/:id`, 15 s).
+ *
+ * @remarks
+ * Mirrors EnriCode (15 s probe budget): offset queries are single-header
+ * reads and must fail fast. Capped by the operator timeout via `Math.min`.
  */
-export interface AnalyzeVisionResponse {
-    /**
-     * Text analysis.
-     */
-    readonly analysis: string;
-    /**
-     * Grounded element boxes for image analyses (original-relative [0,1]).
-     */
-    readonly elements?: ReadonlyArray<{
-        readonly label: string;
-        readonly box: {
-            readonly x: number;
-            readonly y: number;
-            readonly width: number;
-            readonly height: number;
-        };
-    }>;
-    /**
-     * Detected media type.
-     */
-    readonly media_type: string;
-    /**
-     * Extraction metadata.
-     */
-    readonly extraction: Record<string, unknown>;
-}
+export declare const PROBE_CONTROL_TIMEOUT_MS: number;
 /**
- * Error thrown when EnriProxy returns a non-2xx HTTP response.
+ * Budget for the fail-open vision-capability probe (`GET /v1/account/models`, 15 s).
+ *
+ * @remarks
+ * Mirrors EnriCode `assertRemoteVisionCapable` and
+ * `ANALYZE_MEDIA_LIMITS.visionProbeTimeoutMs` (pinned equal by tests): the
+ * probe must never stall session creation.
  */
-export declare class EnriProxyHttpError extends Error {
-    /**
-     * HTTP status code returned by the server.
-     */
-    readonly status: number;
-    /**
-     * Response headers returned by the server.
-     */
-    readonly headers: Record<string, string | string[] | undefined>;
-    /**
-     * Response body returned by the server (best-effort UTF-8).
-     */
-    readonly body: string;
-    /**
-     * Creates a new {@link EnriProxyHttpError}.
-     *
-     * @param message - Error message
-     * @param status - HTTP status code
-     * @param headers - Response headers
-     * @param body - Response body
-     */
-    constructor(message: string, status: number, headers: Record<string, string | string[] | undefined>, body: string);
-}
+export declare const ACCOUNT_MODELS_PROBE_TIMEOUT_MS: number;
 /**
  * Minimal client for EnriProxy HTTP endpoints.
  */
@@ -125,192 +65,295 @@ export declare class EnriProxyClient {
      *
      * @param params - Session parameters
      * @returns Session response
+     * @throws Error with the parsed server detail when creation fails, or when the success body is not valid JSON.
      */
-    createUploadSession(params: {
-        /**
-         * Original filename.
-         */
-        readonly filename: string;
-        /**
-         * Total file size in bytes.
-         */
-        readonly sizeBytes: number;
-        /**
-         * MIME type.
-         */
-        readonly contentType: string;
-        /**
-         * Optional client trace id.
-         */
-        readonly clientTraceId?: string;
-    }): Promise<CreateUploadSessionResponse>;
+    createUploadSession(params: CreateUploadSessionParams): Promise<CreateUploadSessionResponse>;
     /**
      * Queries the current upload offset for a session.
      *
      * @param uploadId - Upload id
+     * @param signal - Optional cancellation signal.
      * @returns Offset in bytes
+     * @throws Error with the parsed server detail when the query fails.
      */
-    getUploadOffset(uploadId: string): Promise<number>;
+    getUploadOffset(uploadId: string, signal?: AbortSignal): Promise<number>;
+    /**
+     * Deletes an upload session and its stored bytes (best-effort orphan cleanup).
+     *
+     * @remarks
+     * Mirrors `DELETE /v1/uploads/:id` on EnriProxy. Callers must invoke this
+     * with an independent timeout signal (never the already-cancelled caller
+     * signal) and swallow failures: cleanup must never mask the original
+     * upload/analysis error.
+     *
+     * @param uploadId - Upload id to delete.
+     * @param signal - Optional cancellation signal (prefer an independent timeout).
+     * @throws Error with an Spanish-first bilingual message when the server rejects the deletion.
+     */
+    deleteUploadSession(uploadId: string, signal?: AbortSignal): Promise<void>;
+    /**
+     * Fetches the account model catalog for the fail-open vision probe.
+     *
+     * @remarks
+     * Thin `GET /v1/account/models` reader for `AnalyzeMediaTool` (mirrors
+     * EnriCode `assertRemoteVisionCapable`): callers treat every failure as
+     * fail-open (proceed with the upload) and only reject on an explicit
+     * `vision === false` match, so a stale discovery snapshot never blocks a
+     * valid upload. Non-2xx responses throw {@link EnriProxyHttpError} (the
+     * caller uses the status to invalidate cached verdicts on 401/404);
+     * non-JSON 2xx bodies throw an Spanish-first bilingual error.
+     *
+     * @param signal - Optional cancellation signal.
+     * @returns Parsed response body.
+     * @throws Error with an Spanish-first bilingual message when the probe request fails.
+     */
+    getAccountModels(signal?: AbortSignal): Promise<unknown>;
     /**
      * Appends a chunk to an upload session.
      *
      * @param params - Chunk parameters
      * @returns New upload offset in bytes
      */
-    appendUploadChunk(params: {
-        /**
-         * Upload session id.
-         */
-        readonly uploadId: string;
-        /**
-         * Expected offset in bytes.
-         */
-        readonly offset: number;
-        /**
-         * Chunk bytes.
-         */
-        readonly chunk: Buffer;
-        /**
-         * Optional timeout override in milliseconds.
-         */
-        readonly timeoutMs?: number;
-    }): Promise<number>;
+    appendUploadChunk(params: AppendUploadChunkParams): Promise<number>;
     /**
      * Triggers server-side vision analysis for an uploaded file.
      *
      * @param params - Analysis parameters
      * @returns Analysis response
+     * @throws Error with the parsed server detail when analysis fails, or when the success body is not valid JSON.
+     */
+    analyze(params: AnalyzeVisionParams): Promise<AnalyzeVisionResponse>;
+    /**
+     * Reads one continuation window over a truncated media list.
+     *
+     * @param params - Cursor plus optional offset/limit.
+     * @returns Page entries with totals and continuation state.
+     * @throws Error with a Spanish-first bilingual message on invalid
+     * cursors, expired cursors, or malformed responses.
+     */
+    fetchSegmentPage(params: FetchSegmentPageParams): Promise<SegmentPageResponse>;
+    /**
+     * Validates one continuation page body.
+     *
+     * @param raw - Parsed response body.
+     * @returns Validated page.
+     * @throws Error with a Spanish-first bilingual message when the body
+     * carries no usable page.
+     */
+    private static requireValidSegmentPage;
+    /**
+     * Rejects oversized prompt text before any byte is uploaded.
+     *
+     * @remarks
+     * Mirrors the parser gate (2000 chars): the server 400s after upload cost.
+     *
+     * @param value - Optional prompt text.
+     * @param fieldName - `question` or `context`.
+     * @throws Error in Spanish naming the 2000-character cap.
+     */
+    private static requireBoundedPromptText;
+    /**
+     * Rejects mistyped tuning before any upload cost on the direct-client path.
+     *
+     * @remarks
+     * Mirrors `AnalyzeMediaParamParser` (enum, language pattern, section
+     * key closure): direct callers bypass the tool parser, and a typo would
+     * otherwise analyze the whole file at full cost. Exposed for reuse and
+     * unit-pinned against the parser key sets.
+     *
+     * @param params - Analysis parameters about to travel.
+     * @throws Error with a Spanish-first bilingual message on the first defect.
+     */
+    static requirePreUploadTuning(params: AnalyzeVisionParams): void;
+    /**
+     * Validates one language hint against the parser pattern.
+     *
+     * @param value - Candidate hint.
+     * @param fieldName - Dotted field name for error messages.
+     * @returns Nothing.
+     * @throws Error with a Spanish-first bilingual message on mismatch.
+     */
+    private static requireLanguageHint;
+    /**
+     * Rejects unknown keys inside one tuning section.
+     *
+     * @param section - Candidate section object.
+     * @param knownKeys - Parser-owned accepted spellings.
+     * @param sectionName - Section name for error messages.
+     * @returns Nothing.
+     * @throws Error with a Spanish-first bilingual message on unknown keys.
+     */
+    private static requireKnownSectionKeys;
+    /**
+     * Rejects per-batch sizes exceeding their totals on the direct-client path.
+     *
+     * @remarks
+     * The tool parser already guards this; direct callers bypass it, and the
+     * server would truncate after paid multipass work.
+     *
+     * @param perBatch - Per-batch value, or undefined when absent.
+     * @param total - Total value, or undefined when absent.
+     * @param family - `document` or `images`.
+     * @throws Error with an Spanish-first bilingual message when the batch exceeds the total.
+     */
+    private static throwOnBatchExceedingTotal;
+    /**
+     * Coerces an optional integer tuning knob, failing loudly on garbage.
+     *
+     * @remarks
+     * Parity with `AnalyzeMediaParamParser` (`optionalInt` accepts `"60"`):
+     * integers and complete integer strings travel floored; any other present
+     * value throws bilingually instead of being silently dropped (a dropped
+     * knob would analyze the whole file at full cost with default tuning).
+     *
+     * @param raw - Raw knob value.
+     * @param fieldName - Dotted field name for error messages.
+     * @param min - Inclusive minimum (shares the parser range table so direct
+     * callers fail pre-upload like parser-gated calls).
+     * @param max - Inclusive maximum (shares the parser range table).
+     * @returns Floored integer, or undefined when absent.
+     * @throws Error with an Spanish-first bilingual message when present but not an integer within range.
+     */
+    private static requireOptionalInt;
+    /**
+     * Coerces an optional float tuning knob, failing loudly on garbage.
+     *
+     * @remarks
+     * Parity with `AnalyzeMediaParamParser` (`optionalNumber` accepts
+     * `"12.5"`): numbers and complete numeric strings travel; any other
+     * present value throws bilingually instead of being silently dropped.
+     *
+     * @param raw - Raw knob value.
+     * @param fieldName - Dotted field name for error messages.
+     * @param min - Inclusive minimum (shares the parser range table).
+     * @param max - Inclusive maximum (shares the parser range table).
+     * @returns Finite number, or undefined when absent.
+     * @throws Error with an Spanish-first bilingual message when present but not a number within range.
+     */
+    private static requireOptionalNumber;
+    /**
+     * Coerces an optional boolean tuning knob, failing loudly on garbage.
+     *
+     * @remarks
+     * Parity with `AnalyzeMediaParamParser` (`assertOptionalBoolean` accepts
+     * `"true"`/`"false"`): booleans and true/false strings travel; any
+     * other present value throws bilingually instead of being silently dropped.
+     *
+     * @param raw - Raw knob value.
+     * @param fieldName - Dotted field name for error messages.
+     * @returns Boolean, or undefined when absent.
+     * @throws Error with an Spanish-first bilingual message when present but not a boolean.
+     */
+    private static requireOptionalBoolean;
+    /**
+     * Resolves the `transcribe` knob, defaulting to true like EnriCode.
+     *
+     * @remarks
+     * A `"false"` string must never collapse to the `true` default (that
+     * would pay a full transcription the caller explicitly disabled):
+     * true/false strings coerce, anything else present throws in Spanish.
+     *
+     * @param raw - Raw transcribe value.
+     * @returns Resolved transcribe flag.
+     * @throws Error with an Spanish-first bilingual message when present but not a boolean nor a true/false string.
      */
-    analyze(params: {
-        /**
-         * Upload session id.
-         */
-        readonly uploadId: string;
-        /**
-         * Optional analysis context hint.
-         */
-        readonly context?: string;
-        /**
-         * Optional explicit question.
-         */
-        readonly question?: string;
-        /**
-         * Preferred response language.
-         */
-        readonly language?: string;
-        /**
-         * Optional max frames override for videos.
-         */
-        readonly maxFrames?: number;
-        /**
-         * Optional override for transcription on videos.
-         */
-        readonly transcribe?: boolean;
-        /**
-         * Optional transcription language hint.
-         */
-        readonly transcriptionLanguage?: string;
-        /**
-         * Optional analysis mode selector.
-         */
-        readonly analysisMode?: "auto" | "single" | "multipass";
-        /**
-         * Optional relative image region for native-resolution zoom (images only).
-         */
-        readonly region?: {
-            readonly x: number;
-            readonly y: number;
-            readonly width: number;
-            readonly height: number;
-        };
-        /**
-         * Optional video multipass tuning.
-         */
-        readonly video?: {
-            /**
-             * Clip start offset in seconds for targeted analysis.
-             */
-            readonly clipStartSeconds?: number;
-            /**
-             * Clip duration in seconds for targeted analysis.
-             */
-            readonly clipDurationSeconds?: number;
-            /**
-             * Segment duration in seconds.
-             */
-            readonly segmentSeconds?: number;
-            /**
-             * Maximum number of segments to analyze.
-             */
-            readonly maxSegments?: number;
-            /**
-             * Maximum frames per segment.
-             */
-            readonly maxFramesPerSegment?: number;
-        };
-        /**
-         * Optional document multipass tuning (PDF).
-         */
-        readonly document?: {
-            /**
-             * Maximum pages to analyze in total.
-             */
-            readonly maxPagesTotal?: number;
-            /**
-             * Pages per batch.
-             */
-            readonly pagesPerBatch?: number;
-            /**
-             * Maximum rendered pages per batch.
-             */
-            readonly maxImagesPerBatch?: number;
-            /**
-             * Minimum extracted text length to treat a page as textual.
-             */
-            readonly scannedTextThresholdChars?: number;
-        };
-        /**
-         * Optional audio multipass tuning.
-         */
-        readonly audio?: {
-            /**
-             * Whether to include timestamped segments in the extracted transcript.
-             */
-            readonly timestamps?: boolean;
-            /**
-             * Segment duration in seconds for audio multipass.
-             */
-            readonly segmentSeconds?: number;
-            /**
-             * Maximum number of audio segments to analyze.
-             */
-            readonly maxSegments?: number;
-        };
-        /**
-         * Optional image-set multipass tuning.
-         */
-        readonly images?: {
-            /**
-             * Maximum number of images to analyze in total.
-             */
-            readonly maxImagesTotal?: number;
-            /**
-             * Images per batch for multipass map calls.
-             */
-            readonly imagesPerBatch?: number;
-            /**
-             * Maximum dimension for images (width/height).
-             */
-            readonly maxDimension?: number;
-        };
-    }): Promise<AnalyzeVisionResponse>;
+    private static requireTranscribe;
+    /**
+     * Validates a `POST /v1/vision/analyze` response body for third-party callers.
+     *
+     * @remarks
+     * A malformed 200 body (`{}`, `analysis: 123`, missing `media_type`)
+     * must surface as a Spanish coaching error, never as an English
+     * `TypeError` from downstream formatters (model-facing text is always
+     * Spanish). Malformed `elements` entries are sanitized (dropped), not
+     * fatal: partial grounding still analyzes.
+     *
+     * @param raw - Parsed response body.
+     * @returns Validated analysis response.
+     * @throws Error with an Spanish-first bilingual message when the body shape is invalid.
+     */
+    private static requireValidAnalyzeResponse;
+    /**
+     * Keeps only well-formed grounded element boxes.
+     *
+     * @remarks
+     * Malformed entries (non-string label, non-finite box coordinates) are
+     * dropped so one bad box never fails the whole analysis; downstream
+     * formatters can assume `{label, box: {x, y, width, height}}`.
+     *
+     * @param elements - Raw elements array from the server.
+     * @returns Sanitized element boxes.
+     */
+    private static sanitizeAnalyzeElements;
+    /**
+     * Builds an {@link EnriProxyHttpError} embedding the parsed server detail.
+     *
+     * @param baseMessage - Base message naming the failed operation with its HTTP status.
+     * @param result - Raw HTTP result carrying headers and body.
+     * @returns HTTP error preserving status, headers, and body.
+     */
+    private static buildHttpError;
+    /**
+     * Parses a 2xx JSON body with a bilingual guard for non-JSON payloads.
+     *
+     * @param body - Raw response body.
+     * @param status - HTTP status code (reported in the error).
+     * @returns Parsed body.
+     * @throws Error with an Spanish-first bilingual message when the body is not valid JSON.
+     */
+    private static parseJsonBody;
     /**
      * Builds an absolute URL relative to the configured base URL.
      *
-     * @param pathname - Pathname to append
+     * @remarks
+     * The base subpath is preserved (`http://host/proxy` + `/v1/uploads` =
+     * `http://host/proxy/v1/uploads`): `new URL(path, base)` alone would
+     * discard it. A root base keeps working exactly as before.
+     *
+     * @param pathname - Pathname to append (must start with `/`).
      * @returns URL instance
+     * @throws Error with an Spanish-first bilingual message when the configured base URL is malformed.
      */
     private buildUrl;
+    /**
+     * Parses a strict `Upload-Offset` response header.
+     *
+     * @remarks
+     * Strict by design: only `^\d+$` (after trimming) is accepted, so
+     * `"12abc"` or `"1.5"` fail bilingually instead of being prefix-parsed
+     * (`parseInt("12abc") === 12`) and resuming at a wrong offset.
+     *
+     * @param headers - Response headers.
+     * @returns Offset in bytes.
+     * @throws Error with an Spanish-first bilingual message when the header is missing or malformed.
+     */
+    private parseUploadOffsetHeader;
+    /**
+     * Validates a relative image region for native-resolution zoom.
+     *
+     * @remarks
+     * Mirrors the `AnalyzeMediaParamParser` region contract (`[0,1]` bounds,
+     * positive size, `x+width<=1`/`y+height<=1`, complete numeric strings
+     * coerced via `optionalFraction`) so direct client callers get the same
+     * Spanish coaching instead of a late server rejection.
+     *
+     * @param region - Raw region value.
+     * @returns Validated region payload.
+     * @throws Error with an Spanish-first bilingual message when the region is malformed or out of range.
+     */
+    private static requireValidRegion;
+    /**
+     * Resolves the session-creation control timeout (60 s, mirrors EnriCode).
+     *
+     * @returns Control timeout in milliseconds (never above 60 s).
+     */
+    private createControlTimeoutMs;
+    /**
+     * Resolves the offset-probe control timeout (15 s, mirrors EnriCode).
+     *
+     * @returns Control timeout in milliseconds (never above 15 s).
+     */
+    private probeControlTimeoutMs;
     /**
      * Extracts a response header as a single string.
      *
@@ -326,6 +369,7 @@ export declare class EnriProxyClient {
      * @param url - Target URL
      * @param jsonBody - JSON payload
      * @param timeoutMs - Timeout in milliseconds
+     * @param signal - Optional cancellation signal.
      * @returns HTTP result
      */
     private requestJson;
@@ -337,6 +381,7 @@ export declare class EnriProxyClient {
      * @param headers - Request headers
      * @param body - Request body
      * @param timeoutMs - Timeout in milliseconds
+     * @param signal - Optional cancellation signal; aborts with a Spanish error.
      * @returns HTTP result
      */
     private requestRaw;