@vinktarhq/cli 0.1.0

package/dist/cjs/http.js

@@ -0,0 +1,211 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RETRIABLE_STATUS = void 0;
+exports.userAgent = userAgent;
+exports.send = send;
+exports.proxyFor = proxyFor;
+exports.retriable = retriable;
+exports.backoffMs = backoffMs;
+exports.timeoutFor = timeoutFor;
+const node_http_1 = require("node:http");
+const node_https_1 = require("node:https");
+const node_net_1 = require("node:net");
+const version_js_1 = require("./version.js");
+/**
+ * `vinktar-cli/<version> (node/<version>)`, plus the plugin when a bundler is driving.
+ *
+ * The server logs it, and "which of these is the Vite plugin and which is a hand-run CI script" is
+ * the first question anyone asks of an ingest log.
+ */
+function userAgent(plugin) {
+    const base = `vinktar-cli/${version_js_1.VERSION} (node/${process.versions.node})`;
+    return plugin === undefined || plugin === '' ? base : `${base} ${plugin}`;
+}
+async function send(options) {
+    const headers = {
+        'User-Agent': userAgent(options.plugin),
+        ...(options.key === undefined || options.key === '' ? {} : { 'X-Vinktar-Key': options.key }),
+        ...options.headers,
+    };
+    const proxy = proxyFor(options.url, options.env ?? process.env);
+    if (proxy !== null)
+        return throughProxy(proxy, options, headers);
+    const response = await fetch(options.url, {
+        method: options.method,
+        headers,
+        ...(options.body === undefined ? {} : { body: options.body }),
+        signal: AbortSignal.timeout(options.timeoutMs),
+    });
+    const text = await response.text();
+    return { status: response.status, text, header: (name) => response.headers.get(name) };
+}
+/**
+ * The proxy that should carry a request to `url`, honouring `NO_PROXY`.
+ *
+ * Lower case wins over upper case, which is what curl does and therefore what people expect:
+ * `http_proxy` is the historical spelling and the one a shell profile sets.
+ */
+function proxyFor(url, env = process.env) {
+    let target;
+    try {
+        target = new URL(url);
+    }
+    catch {
+        return null;
+    }
+    if (bypassed(target.hostname, env['no_proxy'] ?? env['NO_PROXY'] ?? ''))
+        return null;
+    const names = target.protocol === 'https:' ? ['https_proxy', 'HTTPS_PROXY'] : ['http_proxy', 'HTTP_PROXY'];
+    const value = env[names[0]] ?? env[names[1]] ?? '';
+    if (value.trim() === '')
+        return null;
+    try {
+        return new URL(value.includes('://') ? value : `http://${value}`);
+    }
+    catch {
+        return null;
+    }
+}
+function bypassed(hostname, list) {
+    if (list.trim() === '*')
+        return true;
+    const host = hostname.toLowerCase();
+    return list
+        .split(',')
+        .map((entry) => entry.trim().replace(/^\./, '').toLowerCase())
+        .filter((entry) => entry !== '')
+        .some((entry) => host === entry || host.endsWith(`.${entry}`));
+}
+/**
+ * Send through a proxy.
+ *
+ * An https target needs a CONNECT tunnel, because the proxy must not be able to read the key or
+ * the source it is carrying. A plain http target is an absolute-URI request, which is the older
+ * and simpler form the same proxies still speak.
+ */
+async function throughProxy(proxy, options, headers) {
+    const target = new URL(options.url);
+    const secure = target.protocol === 'https:';
+    const socket = secure ? await tunnel(proxy, target, options.timeoutMs) : null;
+    return new Promise((resolve, reject) => {
+        const perform = secure ? node_https_1.request : node_http_1.request;
+        const request = perform(secure
+            ? {
+                method: options.method,
+                host: target.hostname,
+                port: target.port === '' ? 443 : Number(target.port),
+                path: `${target.pathname}${target.search}`,
+                headers,
+                createConnection: () => socket,
+                timeout: options.timeoutMs,
+            }
+            : {
+                method: options.method,
+                host: proxy.hostname,
+                port: proxy.port === '' ? 80 : Number(proxy.port),
+                // Absolute URI: the proxy needs to know where this is going, since there is no tunnel.
+                path: options.url,
+                headers: { ...headers, Host: target.host, ...proxyAuth(proxy) },
+                timeout: options.timeoutMs,
+            }, (response) => {
+            const chunks = [];
+            response.on('data', (chunk) => chunks.push(chunk));
+            response.on('end', () => resolve({
+                status: response.statusCode ?? 0,
+                text: Buffer.concat(chunks).toString('utf8'),
+                header: (name) => {
+                    const value = response.headers[name.toLowerCase()];
+                    return typeof value === 'string' ? value : null;
+                },
+            }));
+        });
+        request.on('timeout', () => request.destroy(new Error(`timed out after ${options.timeoutMs} ms`)));
+        request.on('error', reject);
+        if (options.body !== undefined)
+            request.write(options.body);
+        request.end();
+    });
+}
+function proxyAuth(proxy) {
+    if (proxy.username === '')
+        return {};
+    const credentials = `${decodeURIComponent(proxy.username)}:${decodeURIComponent(proxy.password)}`;
+    return { 'Proxy-Authorization': `Basic ${Buffer.from(credentials).toString('base64')}` };
+}
+/** Open a CONNECT tunnel to the target, over which TLS is then negotiated end to end. */
+async function tunnel(proxy, target, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        const port = proxy.port === '' ? (proxy.protocol === 'https:' ? 443 : 80) : Number(proxy.port);
+        const host = `${target.hostname}:${target.port === '' ? 443 : target.port}`;
+        const auth = proxyAuth(proxy)['Proxy-Authorization'];
+        const client = (0, node_net_1.connect)({ host: proxy.hostname, port }, () => {
+            client.write(`CONNECT ${host} HTTP/1.1\r\nHost: ${host}\r\n` +
+                (auth === undefined ? '' : `Proxy-Authorization: ${auth}\r\n`) +
+                '\r\n');
+        });
+        client.setTimeout(timeoutMs, () => {
+            client.destroy();
+            reject(new Error(`the proxy at ${proxy.host} did not answer within ${timeoutMs} ms`));
+        });
+        client.once('error', reject);
+        client.once('data', (chunk) => {
+            const status = Number(/^HTTP\/1\.[01] (\d{3})/.exec(chunk.toString('latin1'))?.[1] ?? 0);
+            if (status === 200) {
+                client.setTimeout(0);
+                resolve(client);
+                return;
+            }
+            client.destroy();
+            reject(new Error(`the proxy at ${proxy.host} refused a tunnel to ${target.host} (HTTP ${status === 0 ? 'unknown' : status})`));
+        });
+    });
+}
+/** Exposed so the retry policy can be asserted rather than inferred from a stack trace. */
+exports.RETRIABLE_STATUS = new Set([429, 502, 503, 504, 507, 524]);
+const RETRIABLE_CODES = new Set([
+    'ECONNRESET',
+    'ECONNREFUSED',
+    'ETIMEDOUT',
+    'EPIPE',
+    'UND_ERR_SOCKET',
+    'UND_ERR_CONNECT_TIMEOUT',
+]);
+/**
+ * Whether a failed request is worth repeating.
+ *
+ * `ENOTFOUND` is on the list only for the default host: a self-hosted URL that does not resolve is
+ * a typo, and retrying a typo three times with backoff turns a one-second error into a ten-second
+ * one and teaches nobody anything.
+ */
+function retriable(error, isDefaultHost) {
+    const code = error?.cause?.code ?? error?.code ?? '';
+    if (code === 'ENOTFOUND' || code === 'EAI_AGAIN')
+        return isDefaultHost;
+    if (RETRIABLE_CODES.has(code))
+        return true;
+    return error instanceof Error && /terminated|fetch failed|timed out|socket hang up/i.test(error.message);
+}
+/**
+ * How long to wait before trying again.
+ *
+ * `Retry-After` is honoured when the server sends one — it is the only party that knows when its
+ * rate limit resets — and capped, because a proxy answering `Retry-After: 3600` must not hang a
+ * deploy for an hour. Otherwise exponential with jitter, so two builds that fail together do not
+ * retry together.
+ */
+function backoffMs(attempt, retryAfter) {
+    const header = Number(retryAfter ?? 0);
+    if (Number.isFinite(header) && header > 0)
+        return Math.min(60_000, header * 1000);
+    return Math.min(10_000, 1_000 * 2 ** attempt) + Math.floor(Math.random() * 250);
+}
+/**
+ * The deadline for a request carrying `bytes`.
+ *
+ * One flat timeout punishes a large upload for being large: 30 s is generous for a handshake and
+ * mean for 40 MB over a hotel connection. This is the connect-and-settle allowance plus an
+ * assumption of a slow-but-real 1 Mbit/s.
+ */
+function timeoutFor(bytes, base) {
+    return base + Math.ceil(bytes / 131_072) * 1000;
+}

package/dist/cjs/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Programmatic API, for build scripts that would rather call a function than shell out.
+ */
+export { run, parse, VERSION } from './cli.js';
+export { inject, audit, type InjectResult, type AuditResult, type AuditEntry } from './commands/inject.js';
+export { upload, type UploadCommandOptions, type UploadSummary, type StoredMap } from './commands/upload.js';
+export { doctor, type DoctorOptions } from './commands/doctor.js';
+export { resolvePosition, type ResolveResult, type Position } from './commands/resolve.js';
+export { resolve as resolveConfig, type Resolved, type Sources } from './config.js';
+export { loadDotEnv, type DotEnv } from './env.js';
+export { matches as globMatches } from './glob.js';
+export { deriveDebugId, registrationSnippet, isDebugId, REGISTRY_GLOBAL, MARKER_GLOBAL, } from './debug-id.js';
+export { discover, isEmptyMap, type Artifact, type Discovery } from './discover.js';
+export { toUrl, normalise } from './url.js';
+export { UploadError, rewrite, type UploadOptions, type UploadResult, type Limits } from './upload.js';
+export { MAX_FILE_BYTES, MAX_NAME_BYTES, MAX_REQUEST_BYTES, RECOMMENDED_BATCH_BYTES, REQUIRED_SCOPE, DEFAULT_HOST, } from './limits.js';
+export { detectRelease, disabled, environmentWarnings, session, finish, type BundlerOptions, type Session, } from './bundler/core.js';

package/dist/cjs/index.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.finish = exports.session = exports.environmentWarnings = exports.disabled = exports.detectRelease = exports.DEFAULT_HOST = exports.REQUIRED_SCOPE = exports.RECOMMENDED_BATCH_BYTES = exports.MAX_REQUEST_BYTES = exports.MAX_NAME_BYTES = exports.MAX_FILE_BYTES = exports.rewrite = exports.UploadError = exports.normalise = exports.toUrl = exports.isEmptyMap = exports.discover = exports.MARKER_GLOBAL = exports.REGISTRY_GLOBAL = exports.isDebugId = exports.registrationSnippet = exports.deriveDebugId = exports.globMatches = exports.loadDotEnv = exports.resolveConfig = exports.resolvePosition = exports.doctor = exports.upload = exports.audit = exports.inject = exports.VERSION = exports.parse = exports.run = void 0;
+/**
+ * Programmatic API, for build scripts that would rather call a function than shell out.
+ */
+var cli_js_1 = require("./cli.js");
+Object.defineProperty(exports, "run", { enumerable: true, get: function () { return cli_js_1.run; } });
+Object.defineProperty(exports, "parse", { enumerable: true, get: function () { return cli_js_1.parse; } });
+Object.defineProperty(exports, "VERSION", { enumerable: true, get: function () { return cli_js_1.VERSION; } });
+var inject_js_1 = require("./commands/inject.js");
+Object.defineProperty(exports, "inject", { enumerable: true, get: function () { return inject_js_1.inject; } });
+Object.defineProperty(exports, "audit", { enumerable: true, get: function () { return inject_js_1.audit; } });
+var upload_js_1 = require("./commands/upload.js");
+Object.defineProperty(exports, "upload", { enumerable: true, get: function () { return upload_js_1.upload; } });
+var doctor_js_1 = require("./commands/doctor.js");
+Object.defineProperty(exports, "doctor", { enumerable: true, get: function () { return doctor_js_1.doctor; } });
+var resolve_js_1 = require("./commands/resolve.js");
+Object.defineProperty(exports, "resolvePosition", { enumerable: true, get: function () { return resolve_js_1.resolvePosition; } });
+var config_js_1 = require("./config.js");
+Object.defineProperty(exports, "resolveConfig", { enumerable: true, get: function () { return config_js_1.resolve; } });
+var env_js_1 = require("./env.js");
+Object.defineProperty(exports, "loadDotEnv", { enumerable: true, get: function () { return env_js_1.loadDotEnv; } });
+var glob_js_1 = require("./glob.js");
+Object.defineProperty(exports, "globMatches", { enumerable: true, get: function () { return glob_js_1.matches; } });
+var debug_id_js_1 = require("./debug-id.js");
+Object.defineProperty(exports, "deriveDebugId", { enumerable: true, get: function () { return debug_id_js_1.deriveDebugId; } });
+Object.defineProperty(exports, "registrationSnippet", { enumerable: true, get: function () { return debug_id_js_1.registrationSnippet; } });
+Object.defineProperty(exports, "isDebugId", { enumerable: true, get: function () { return debug_id_js_1.isDebugId; } });
+Object.defineProperty(exports, "REGISTRY_GLOBAL", { enumerable: true, get: function () { return debug_id_js_1.REGISTRY_GLOBAL; } });
+Object.defineProperty(exports, "MARKER_GLOBAL", { enumerable: true, get: function () { return debug_id_js_1.MARKER_GLOBAL; } });
+var discover_js_1 = require("./discover.js");
+Object.defineProperty(exports, "discover", { enumerable: true, get: function () { return discover_js_1.discover; } });
+Object.defineProperty(exports, "isEmptyMap", { enumerable: true, get: function () { return discover_js_1.isEmptyMap; } });
+var url_js_1 = require("./url.js");
+Object.defineProperty(exports, "toUrl", { enumerable: true, get: function () { return url_js_1.toUrl; } });
+Object.defineProperty(exports, "normalise", { enumerable: true, get: function () { return url_js_1.normalise; } });
+var upload_js_2 = require("./upload.js");
+Object.defineProperty(exports, "UploadError", { enumerable: true, get: function () { return upload_js_2.UploadError; } });
+Object.defineProperty(exports, "rewrite", { enumerable: true, get: function () { return upload_js_2.rewrite; } });
+var limits_js_1 = require("./limits.js");
+Object.defineProperty(exports, "MAX_FILE_BYTES", { enumerable: true, get: function () { return limits_js_1.MAX_FILE_BYTES; } });
+Object.defineProperty(exports, "MAX_NAME_BYTES", { enumerable: true, get: function () { return limits_js_1.MAX_NAME_BYTES; } });
+Object.defineProperty(exports, "MAX_REQUEST_BYTES", { enumerable: true, get: function () { return limits_js_1.MAX_REQUEST_BYTES; } });
+Object.defineProperty(exports, "RECOMMENDED_BATCH_BYTES", { enumerable: true, get: function () { return limits_js_1.RECOMMENDED_BATCH_BYTES; } });
+Object.defineProperty(exports, "REQUIRED_SCOPE", { enumerable: true, get: function () { return limits_js_1.REQUIRED_SCOPE; } });
+Object.defineProperty(exports, "DEFAULT_HOST", { enumerable: true, get: function () { return limits_js_1.DEFAULT_HOST; } });
+var core_js_1 = require("./bundler/core.js");
+Object.defineProperty(exports, "detectRelease", { enumerable: true, get: function () { return core_js_1.detectRelease; } });
+Object.defineProperty(exports, "disabled", { enumerable: true, get: function () { return core_js_1.disabled; } });
+Object.defineProperty(exports, "environmentWarnings", { enumerable: true, get: function () { return core_js_1.environmentWarnings; } });
+Object.defineProperty(exports, "session", { enumerable: true, get: function () { return core_js_1.session; } });
+Object.defineProperty(exports, "finish", { enumerable: true, get: function () { return core_js_1.finish; } });

package/dist/cjs/limits.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The limits the ingest API enforces.
+ *
+ * Fallbacks, not the truth: `POST /v1/sourcemaps/check` publishes what a deployment actually
+ * accepts, and the client prefers that (see {@link ../upload.js}). These are what it uses before
+ * it has asked, and against an older ingest that does not publish them — so a 60 MB upload fails
+ * in a second with a clear message rather than after the bytes have crossed the wire.
+ */
+/** Per map. Over this the server answers 413 file_too_large. */
+export declare const MAX_FILE_BYTES = 20971520;
+/** Whole multipart request. */
+export declare const MAX_REQUEST_BYTES = 62914560;
+/**
+ * What one request should carry when the server is configured as the protocol says.
+ *
+ * The server publishes its own figure as `maxBatchBytes` at `POST /v1/sourcemaps/check`, computed
+ * from its actual `post_max_size`; this is the same number the protocol recommends, mirrored so a
+ * test can assert the two have not drifted.
+ */
+export declare const RECOMMENDED_BATCH_BYTES = 16777216;
+/**
+ * What one request carries when the server says nothing.
+ *
+ * An ingest that does not publish `limits` is one deployed before they existed, and a deployment
+ * that old is one whose `post_max_size` is very likely PHP's stock 8M. A POST over that is not
+ * rejected — the body is silently discarded and the server answers `missing_release`, which reads
+ * like a CLI bug and cost an afternoon to diagnose the first time. Batching under the ini default
+ * works everywhere; the extra requests cost seconds.
+ */
+export declare const CONSERVATIVE_BATCH_BYTES = 6000000;
+/** The longest a release or dist name may be. Over it the server answers `invalid_release`. */
+export declare const MAX_NAME_BYTES = 64;
+/** Source-map upload needs `cli` scope, NOT `write`. A write key alone gets a 403. */
+export declare const REQUIRED_SCOPE = "cli";
+export declare const DEFAULT_HOST = "https://in.vinktar.com";

package/dist/cjs/limits.js

@@ -0,0 +1,38 @@
+"use strict";
+/**
+ * The limits the ingest API enforces.
+ *
+ * Fallbacks, not the truth: `POST /v1/sourcemaps/check` publishes what a deployment actually
+ * accepts, and the client prefers that (see {@link ../upload.js}). These are what it uses before
+ * it has asked, and against an older ingest that does not publish them — so a 60 MB upload fails
+ * in a second with a clear message rather than after the bytes have crossed the wire.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_HOST = exports.REQUIRED_SCOPE = exports.MAX_NAME_BYTES = exports.CONSERVATIVE_BATCH_BYTES = exports.RECOMMENDED_BATCH_BYTES = exports.MAX_REQUEST_BYTES = exports.MAX_FILE_BYTES = void 0;
+/** Per map. Over this the server answers 413 file_too_large. */
+exports.MAX_FILE_BYTES = 20_971_520;
+/** Whole multipart request. */
+exports.MAX_REQUEST_BYTES = 62_914_560;
+/**
+ * What one request should carry when the server is configured as the protocol says.
+ *
+ * The server publishes its own figure as `maxBatchBytes` at `POST /v1/sourcemaps/check`, computed
+ * from its actual `post_max_size`; this is the same number the protocol recommends, mirrored so a
+ * test can assert the two have not drifted.
+ */
+exports.RECOMMENDED_BATCH_BYTES = 16_777_216;
+/**
+ * What one request carries when the server says nothing.
+ *
+ * An ingest that does not publish `limits` is one deployed before they existed, and a deployment
+ * that old is one whose `post_max_size` is very likely PHP's stock 8M. A POST over that is not
+ * rejected — the body is silently discarded and the server answers `missing_release`, which reads
+ * like a CLI bug and cost an afternoon to diagnose the first time. Batching under the ini default
+ * works everywhere; the extra requests cost seconds.
+ */
+exports.CONSERVATIVE_BATCH_BYTES = 6_000_000;
+/** The longest a release or dist name may be. Over it the server answers `invalid_release`. */
+exports.MAX_NAME_BYTES = 64;
+/** Source-map upload needs `cli` scope, NOT `write`. A write key alone gets a 403. */
+exports.REQUIRED_SCOPE = 'cli';
+exports.DEFAULT_HOST = 'https://in.vinktar.com';

package/dist/cjs/multipart.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Building the upload body by hand instead of with `FormData`.
+ *
+ * Three reasons, in order of how much each one costs when it is missing:
+ *
+ * 1. **A proxy.** Node's `fetch` ignores `HTTPS_PROXY`, so a request through one has to go out
+ *    over `node:https`, which needs bytes rather than a `FormData` object.
+ * 2. **Per-part compression.** `Content-Encoding` does not survive multipart parsing — PHP hands
+ *    the handler the raw part and nothing else — so a compressed part is just a part whose bytes
+ *    happen to be gzip, detected by its magic number. That means putting exact bytes in a part.
+ * 3. **Knowing the size before sending.** The ceiling that matters is the encoded request, not the
+ *    sum of the files, and the framing is not free: a hundred parts is several kilobytes of
+ *    boundaries and headers.
+ */
+export interface Part {
+    readonly name: string;
+    readonly value: string | Buffer;
+    /** Present for a file part, absent for a plain field. */
+    readonly filename?: string;
+    readonly contentType?: string;
+}
+export interface Multipart {
+    readonly body: Buffer;
+    readonly contentType: string;
+}
+export declare function multipart(parts: readonly Part[]): Multipart;
+/** What one part costs on the wire beyond its own bytes, for planning a batch. */
+export declare function overheadFor(part: Part): number;

package/dist/cjs/multipart.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.multipart = multipart;
+exports.overheadFor = overheadFor;
+const node_crypto_1 = require("node:crypto");
+function multipart(parts) {
+    // Random rather than derived from the content: a boundary that appears inside a file would
+    // truncate the request, and the odds of guessing 16 random bytes are not worth defending against
+    // any other way.
+    const boundary = `----vinktar${(0, node_crypto_1.randomBytes)(16).toString('hex')}`;
+    const chunks = [];
+    for (const part of parts) {
+        const disposition = part.filename === undefined
+            ? `form-data; name="${escape(part.name)}"`
+            : `form-data; name="${escape(part.name)}"; filename="${escape(part.filename)}"`;
+        chunks.push(Buffer.from(`--${boundary}\r\nContent-Disposition: ${disposition}\r\n` +
+            (part.contentType === undefined ? '' : `Content-Type: ${part.contentType}\r\n`) +
+            '\r\n', 'utf8'));
+        chunks.push(typeof part.value === 'string' ? Buffer.from(part.value, 'utf8') : part.value);
+        chunks.push(Buffer.from('\r\n', 'utf8'));
+    }
+    chunks.push(Buffer.from(`--${boundary}--\r\n`, 'utf8'));
+    return {
+        body: Buffer.concat(chunks),
+        contentType: `multipart/form-data; boundary=${boundary}`,
+    };
+}
+/**
+ * Quote what a header field cannot carry raw.
+ *
+ * Names here are ours (`files[]`, `urls[]`) and filenames come from a build directory, so this is
+ * belt and braces — but a filename with a quote in it would otherwise end the field early and
+ * mis-pair every part after it, which is the one failure in this format that is invisible.
+ */
+function escape(value) {
+    return value.replace(/[\r\n"]/g, (match) => (match === '"' ? '%22' : ''));
+}
+/** What one part costs on the wire beyond its own bytes, for planning a batch. */
+function overheadFor(part) {
+    return (100 +
+        Buffer.byteLength(part.name) +
+        Buffer.byteLength(part.filename ?? '') +
+        Buffer.byteLength(part.contentType ?? ''));
+}

package/dist/cjs/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

package/dist/cjs/upload.d.ts

@@ -0,0 +1,178 @@
+import { type Artifact } from './discover.js';
+/**
+ * Uploads source maps to `POST /v1/sourcemaps`.
+ *
+ * `files[]`, `urls[]` and `debug_ids[]` are **positional parallel arrays**: the server pairs them
+ * by index, so appending to one without the others silently mis-pairs every entry after it. They
+ * are therefore built in one loop and never separately.
+ */
+export interface UploadOptions {
+    readonly host: string;
+    readonly key: string;
+    readonly release: string;
+    readonly dist?: string;
+    readonly urlPrefix: string;
+    /** Per request, before the size allowance. Default 30 s. */
+    timeoutMs?: number;
+    /** Requests in flight. Default 4, or whatever the server asks for. */
+    concurrency?: number;
+    /** Attempts per request, including the first. Default 3. */
+    maxRetries?: number;
+    /** Extra headers, for a gateway that wants one. Never allowed to displace the key. */
+    headers?: Readonly<Record<string, string>>;
+    /** Appended to the User-Agent, so an ingest log can tell a plugin from a CI script. */
+    plugin?: string;
+    /**
+     * Rewrite `sources` in the uploaded copy. Default true — see {@link rewrite}.
+     * The file on disk is never touched.
+     */
+    rewriteSources?: boolean;
+    /** The build root, which absolute `sources` are made relative to. */
+    root?: string;
+    env?: Record<string, string | undefined>;
+}
+/** What this deployment will actually accept, as it reports it. */
+export interface Limits {
+    readonly maxFileBytes: number;
+    readonly maxPartBytes: number;
+    readonly maxRequestBytes: number;
+    readonly recommendedBatchBytes: number;
+    readonly concurrency: number;
+    readonly compression: readonly string[];
+}
+export interface UploadEntry {
+    readonly name: string;
+    readonly url: string;
+    readonly debugId: string;
+    readonly bytes: number;
+    /** Content hash of the exact body that would be uploaded. The server's dedupe key. */
+    readonly sha256: string;
+    /**
+     * Content hash of the map FILE as it sits on disk, which is a different string: the uploaded
+     * body carries the debug id and, when a line was inserted, a shifted `mappings`.
+     *
+     * Only the plugins use it, and only to answer one question before deleting a map: are these
+     * still the bytes that were uploaded? Turbopack rewrites files while later stages run, and a
+     * map deleted there is one the server never received.
+     */
+    readonly mapSha256: string;
+    /**
+     * Whether the chunk itself carries the id. When false the id was derived here for the map only,
+     * and no frame will ever report it: the map can then match by release + url alone.
+     */
+    readonly injected: boolean;
+}
+export interface UploadResult {
+    readonly stored: number;
+    readonly artifacts: ReadonlyArray<{
+        file_url?: string;
+        debug_id?: string;
+        size?: number;
+    }>;
+}
+export declare class UploadError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly hint?: string | undefined;
+    constructor(message: string, status: number, code: string, hint?: string | undefined);
+}
+/**
+ * Index one artifact: what it is, what it hashes to, and how big it will be on the wire.
+ *
+ * The body is built and then DISCARDED. Holding it would mean the whole build sitting in memory
+ * before the first request left — a few hundred chunks of a real application is hundreds of
+ * megabytes — and it is cheap to rebuild from a local file at the moment it is actually sent.
+ *
+ * Returns null when there is nothing to upload, rather than throwing: a directory of chunks where
+ * only some have maps is normal, not an error.
+ */
+export declare function index(artifact: Artifact, urlPrefix: string, options?: Pick<UploadOptions, 'rewriteSources' | 'root'>): Promise<{
+    entry: UploadEntry;
+    oversized: boolean;
+    empty: boolean;
+} | null>;
+/**
+ * The exact bytes that go on the wire for this artifact.
+ *
+ * Deterministic, which is what lets `index` throw the body away and this rebuild it later: the id
+ * already injected into the chunk wins, so a second call cannot produce a different map than the
+ * one that was hashed.
+ */
+export declare function materialise(artifact: Artifact, options?: Pick<UploadOptions, 'rewriteSources' | 'root'>): Promise<string>;
+/**
+ * Tidy `sources` in the uploaded copy, never on disk.
+ *
+ * Two things come out of a bundler that should not reach a server. `webpack:///./src/App.tsx` is
+ * a protocol nothing can open, and it is what the UI would print beside every frame. And an
+ * absolute path is the build machine's directory layout — `/home/runner/work/acme/acme/src/…`, or
+ * worse, someone's home directory — which is both noise and information the ingest never asked
+ * for.
+ *
+ * The uploaded copy only. Rewriting the file would change bytes another tool may already have
+ * hashed, and the map on disk is the one a developer opens locally, where an absolute path is
+ * exactly what they want.
+ */
+export declare function rewrite(mapJson: string, root?: string): string;
+export interface Preflight {
+    /** sha256 of the bodies the server already holds. */
+    readonly stored: Set<string>;
+    /** What this deployment accepts, when it says. Null on an older ingest, or an unreachable one. */
+    readonly limits: Limits | null;
+}
+/**
+ * Ask the server which of these bodies it already holds, and what it will accept.
+ *
+ * The dedupe half is purely an optimisation, so every failure mode answers "none": an older ingest
+ * with no such route, a proxy in the way, a network blip. Uploading something the server already
+ * has is a wasted request; NOT uploading something it does not have is a build with no
+ * symbolication, and those are not the same mistake.
+ *
+ * The limits half matters more than it looks. The protocol says 20 MiB per file and 60 MiB per
+ * request, but what a deployment actually accepts is the smaller of that and its PHP
+ * `upload_max_filesize` / `post_max_size` — and a POST over `post_max_size` is not rejected, the
+ * body is silently dropped and the server answers `missing_release`, which reads like a CLI bug.
+ * Asking is the difference between a clear message and an afternoon.
+ */
+export declare function preflight(options: UploadOptions, hashes: readonly string[]): Promise<Preflight>;
+/** Four at a time: enough to hide the latency, few enough not to trip the ingest rate limit. */
+export declare const DEFAULT_CONCURRENCY = 4;
+/**
+ * Send one batch.
+ *
+ * Batches are bounded by the request ceiling rather than by count: maps vary from kilobytes to
+ * megabytes, so a fixed count would either waste requests or overshoot.
+ *
+ * Each part is gzipped when the server says it accepts that. `Content-Encoding` does NOT survive
+ * multipart parsing — PHP hands the handler the raw part and nothing else — so a compressed part
+ * is simply a part whose bytes are gzip, which the server detects by its magic number. Source maps
+ * are JSON with long runs of repeated source text and compress by 80–90%, which is the difference
+ * between one request and six.
+ */
+export declare function send(options: UploadOptions, batch: ReadonlyArray<{
+    entry: UploadEntry;
+    body: string;
+}>, limits?: Limits | null): Promise<UploadResult>;
+/**
+ * Group indexed maps into requests that fit.
+ *
+ * The budget is approached with headroom, because multipart framing and the field names add bytes
+ * the file sizes do not account for, and an oversized request costs the whole batch. Sized on the
+ * UNCOMPRESSED bodies even when the parts will be gzipped: compression only ever makes the request
+ * smaller, so the bound stays true and one batch's worth of maps is still what sits in memory.
+ *
+ * Generic over whatever the caller is carrying alongside the entry, so a batch can hold the
+ * artifact each map came from and the body can be read back from disk as its batch is sent —
+ * nothing here pins the build in memory.
+ */
+export declare function batch<T extends {
+    readonly entry: UploadEntry;
+}>(items: readonly T[], limits?: Limits | null): T[][];
+/**
+ * Run `work` over `items` with a bounded number in flight.
+ *
+ * Source maps are large and the server is usually far away, so a build of two hundred chunks spent
+ * most of its upload waiting on a socket. Bounded rather than unbounded: an unbounded fan-out of
+ * 6 MB requests is how a deploy step gets itself rate-limited.
+ */
+export declare function pooled<T, R>(items: readonly T[], limit: number, work: (item: T, index: number) => Promise<R>): Promise<R[]>;
+export declare function mb(bytes: number): string;