@plune-ai/cli 0.17.0 → 0.18.0

package/dist/reporter-core.cjs

@@ -49,7 +49,7 @@ module.exports = __toCommonJS(reporter_core_exports);
 
 // src/reporter-core/session.ts
 var import_node_crypto = require("crypto");
-var import_node_fs3 = require("fs");
+var import_node_fs4 = require("fs");
 var import_node_path3 = require("path");
 var import_node_util2 = require("util");
 
@@ -80,6 +80,8 @@ function loadToken() {
 }
 
 // src/reporter-core/client.ts
+var import_node_fs2 = require("fs");
+var import_node_stream = require("stream");
 var import_node_http = require("http");
 var import_node_https = require("https");
 var RETRY_DELAYS_MS = [300, 900];
@@ -113,13 +115,49 @@ function nodeTransport(url, init, idleMs = IDLE_MS) {
     req.end(init.body);
   });
 }
+var PUT_DELAYS_MS = [500, 1500, 4e3];
+var withoutLength = (headers) => Object.fromEntries(Object.entries(headers).filter(([name]) => name.toLowerCase() !== "content-length"));
+function nodePut(url, headers, source, idleMs) {
+  return new Promise((resolve2, reject) => {
+    const target = new URL(url);
+    const send = target.protocol === "https:" ? import_node_https.request : import_node_http.request;
+    const length = "body" in source ? source.body.length : source.size;
+    let answered;
+    const settle = (err) => answered !== void 0 ? resolve2(answered) : reject(err);
+    const req = send(
+      target,
+      { method: "PUT", headers: { ...withoutLength(headers), "content-length": String(length) } },
+      (res) => {
+        const retry = res.headers["retry-after"];
+        answered = { status: res.statusCode ?? 0, retryAfter: Array.isArray(retry) ? retry[0] ?? null : retry ?? null };
+        res.on("error", settle);
+        res.on("close", () => {
+          resolve2(answered);
+          req.destroy();
+        });
+        res.resume();
+      }
+    );
+    req.setTimeout(idleMs, () => req.destroy(Object.assign(new Error("idle"), { code: "ETIMEDOUT" })));
+    req.on("error", settle);
+    if ("body" in source) req.end(source.body);
+    else (0, import_node_stream.pipeline)((0, import_node_fs2.createReadStream)(source.path), req, (err) => err ? settle(err) : void 0);
+  });
+}
+var codeOfError = (err) => {
+  const code = err?.code;
+  return typeof code === "string" && /^[A-Z0-9_]{2,40}$/.test(code) ? code : "network";
+};
 var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 async function detailOf(res) {
   try {
     const body = await res.json();
-    return typeof body.error === "string" ? body.error : "";
+    return {
+      detail: typeof body.error === "string" ? body.error : "",
+      ...typeof body.code === "string" && /^[a-z0-9_]{1,60}$/.test(body.code) ? { code: body.code } : {}
+    };
   } catch {
-    return "";
+    return { detail: "" };
   }
 }
 function retryAfterMs(res) {
@@ -170,10 +208,16 @@ function createClient(opts) {
           return { ok: false, kind: "other", status: res.status, detail: "the answer was not JSON" };
         }
       }
-      const detail = scrub(await detailOf(res));
+      const said = await detailOf(res);
       const kind = classify(res.status);
-      last = { kind, status: res.status, detail };
+      last = { kind, status: res.status, detail: scrub(said.detail), ...said.code !== void 0 ? { code: said.code } : {} };
       if (kind !== "unavailable") break;
+      if (res.status === 429 && retryAfterMs(res) === null) {
+        last.kind = "invalid";
+        last.detail = "quota exceeded (no Retry-After)";
+        if (said.detail) last.detail += ` \u2014 ${scrub(said.detail)}`;
+        break;
+      }
       if (attempt < RETRY_DELAYS_MS.length) {
         await wait(retryAfterMs(res) ?? RETRY_DELAYS_MS[attempt]);
       }
@@ -183,7 +227,36 @@ function createClient(opts) {
   return {
     post: (path3, body) => send("POST", path3, { body: JSON.stringify(body), type: "application/json" }),
     upload: (path3, bytes, contentType) => send("POST", path3, { body: bytes, type: contentType }),
-    del: (path3) => send("DELETE", path3)
+    del: (path3) => send("DELETE", path3),
+    async put(url, headers, source) {
+      let last = { ok: false, status: null, code: "network" };
+      for (let attempt = 0; attempt <= PUT_DELAYS_MS.length; attempt += 1) {
+        try {
+          let status;
+          let retryAfter;
+          if (opts.fetchImpl === void 0) ({ status, retryAfter } = await nodePut(url, headers, source, IDLE_MS));
+          else {
+            const body = "body" in source ? source.body : await (0, import_node_fs2.openAsBlob)(source.path);
+            const res = await opts.fetchImpl(url, { method: "PUT", headers: withoutLength(headers), body });
+            await res.arrayBuffer().catch(() => void 0);
+            status = res.status;
+            retryAfter = res.headers.get("retry-after");
+          }
+          if (status >= 200 && status <= 299) return { ok: true };
+          last = { ok: false, status, code: `bucket_${status}` };
+          if (status < 500 && status !== 429) return last;
+          const seconds = retryAfter === null ? NaN : Number(retryAfter.trim());
+          if (attempt < PUT_DELAYS_MS.length) {
+            await wait(Number.isFinite(seconds) && seconds >= 0 ? Math.min(seconds, 60) * 1e3 : PUT_DELAYS_MS[attempt]);
+          }
+          continue;
+        } catch (err) {
+          last = { ok: false, status: null, code: codeOfError(err) };
+        }
+        if (attempt < PUT_DELAYS_MS.length) await wait(PUT_DELAYS_MS[attempt]);
+      }
+      return last;
+    }
   };
 }
 
@@ -273,7 +346,7 @@ function ciCommit(reported, env = process.env) {
 }
 
 // src/reporter-core/failure-detail.ts
-var import_node_fs2 = require("fs");
+var import_node_fs3 = require("fs");
 var import_node_os2 = require("os");
 var import_node_path2 = require("path");
 var import_node_util = require("util");
@@ -296,7 +369,7 @@ function failureOf(attempt, home = (0, import_node_os2.homedir)()) {
 }
 function repoRootOf(dir, stopAt) {
   for (let here = (0, import_node_path2.resolve)(dir); ; here = (0, import_node_path2.dirname)(here)) {
-    if ((0, import_node_fs2.existsSync)((0, import_node_path2.join)(here, ".git"))) return here;
+    if ((0, import_node_fs3.existsSync)((0, import_node_path2.join)(here, ".git"))) return here;
     if (here === stopAt || (0, import_node_path2.dirname)(here) === here) return void 0;
   }
 }
@@ -304,6 +377,7 @@ function errorContextOf(attempt, home = (0, import_node_os2.homedir)()) {
   const text = attempt.errors.map((e) => e.text).filter((t) => t !== "").join("\n\n");
   return cut(machineless(text, attempt.repoRoot, home));
 }
+var printable = (text) => text.replace(/[\u0000-\u001f\u007f-\u009f]/g, "?");
 var mediaTypeOf = (contentType) => contentType?.split(";")[0]?.trim().toLowerCase() || void 0;
 var TEXT_TYPES = /* @__PURE__ */ new Set(["application/json", "text/plain"]);
 var isTextType = (contentType) => TEXT_TYPES.has(mediaTypeOf(contentType) ?? "");
@@ -442,6 +516,7 @@ var TYPE_BY_EXTENSION = {
   ".jpeg": "image/jpeg",
   ".webp": "image/webp"
 };
+var METADATA_TYPE2 = "application/plune.metadata+json";
 var UPLOADS_AT_ONCE = 4;
 var NAME_MAX = 200;
 function nameOf(file) {
@@ -467,15 +542,26 @@ var SKIPPED = {
   textSize: "Plune takes a text file of at most 512 KiB",
   empty: "the file is empty",
   binary: "the file holds a NUL byte, and Plune takes UTF-8 text without one",
-  encoding: "Plune takes UTF-8 text only"
+  encoding: "Plune takes UTF-8 text only",
+  noStorage: "no storage bucket is connected to this project"
 };
+var BUCKET_FOUND = "plune: storage bucket found for this project \u2014 screenshots, text, trace and video go straight to it over short-lived links.";
 var KINDS = {
   screenshot: { label: "screenshot", bytes: SCREENSHOT_BYTES, room: SCREENSHOTS_PER_RESULT, limit: "limit", size: "size" },
-  text: { label: "text file", bytes: TEXT_BYTES, room: TEXTS_PER_RESULT, limit: "textLimit", size: "textSize" }
+  text: { label: "text file", bytes: TEXT_BYTES, room: TEXTS_PER_RESULT, limit: "textLimit", size: "textSize" },
+  // Only the label is used: a file of this kind has no home in the database, so no ceiling of its own is known here.
+  file: { label: "file", bytes: 0, room: 0, limit: "limit", size: "size" }
 };
 function kindOf(type) {
   if (type.startsWith("image/")) return "screenshot";
-  return TEXT_TYPES.has(type) ? "text" : void 0;
+  return TEXT_TYPES.has(type) ? "text" : "file";
+}
+var codeOf = (out) => out.code ?? (out.status === null ? "network" : `http_${out.status}`);
+function linkOf(item) {
+  const link = item;
+  if (typeof link?.id !== "string" || typeof link.url !== "string") return void 0;
+  const headers = typeof link.headers === "object" && link.headers !== null ? link.headers : {};
+  return { id: link.id, url: link.url, headers };
 }
 function textTypeOf(contentType, type) {
   const charset = /;\s*charset\s*=\s*"?([^\s";]+)"?/i.exec(contentType)?.[1];
@@ -578,7 +664,8 @@ async function startRun(passed, declared) {
     unoffered: 0,
     deferred: 0,
     screenshots: { uploaded: 0, skipped: 0, failed: 0 },
-    textFiles: { uploaded: 0, skipped: 0, failed: 0 }
+    textFiles: { uploaded: 0, skipped: 0, failed: 0 },
+    otherFiles: { uploaded: 0, skipped: 0, failed: 0 }
   };
   const resolved = /* @__PURE__ */ new Map();
   let buffer = [];
@@ -589,7 +676,13 @@ async function startRun(passed, declared) {
   let done = false;
   const shortened = /* @__PURE__ */ new Set();
   const skipsSaid = /* @__PURE__ */ new Set();
-  const countsOf = (kind) => kind === "text" ? stats.textFiles : stats.screenshots;
+  const countsOf = (kind) => kind === "text" ? stats.textFiles : kind === "file" ? stats.otherFiles : stats.screenshots;
+  let bucketSeen = false;
+  let noStorage = 0;
+  let uploadsMissing = false;
+  const failedSaid = /* @__PURE__ */ new Set();
+  const codesSaid = /* @__PURE__ */ new Set();
+  const rooms = /* @__PURE__ */ new Map();
   function bound(keys) {
     return keys.map((key) => {
       const fit = boundKey(key);
@@ -597,7 +690,7 @@ async function startRun(passed, declared) {
         shortened.add(key.value);
         if (shortened.size === 1) {
           log(
-            `plune: a test name longer than ${KEY_MAX} characters was shortened to fit its key \u2014 "${key.value.slice(0, 80)}\u2026". Give the test a shorter name; until then this is its identity.`
+            `plune: a test name longer than ${KEY_MAX} characters was shortened to fit its key \u2014 ${JSON.stringify(printable(key.value.slice(0, 80)))}\u2026 Give the test a shorter name; until then this is its identity.`
           );
         }
       }
@@ -727,20 +820,49 @@ async function startRun(passed, declared) {
   }
   function skip(kind, name, why) {
     countsOf(kind).skipped += 1;
-    if (skipsSaid.has(`${kind}/${why}`)) return;
-    skipsSaid.add(`${kind}/${why}`);
-    log(`plune: ${KINDS[kind].label} "${name}" not uploaded \u2014 ${SKIPPED[why]}.`);
+    if (why === "noStorage") noStorage += 1;
+    const said = why === "noStorage" ? why : `${kind}/${why}`;
+    if (skipsSaid.has(said)) return;
+    skipsSaid.add(said);
+    if (why === "noStorage") log(`plune: "${name}" not stored \u2014 ${SKIPPED[why]}.`);
+    else log(`plune: ${KINDS[kind].label} "${name}" not uploaded \u2014 ${SKIPPED[why]}.`);
   }
-  async function uploadOne(job) {
+  function ask(job, size) {
+    return client.post(`/v1/results/${encodeURIComponent(job.id)}/files/uploads`, {
+      files: [{ name: job.name, contentType: job.type, size }]
+    });
+  }
+  function failed(job, why) {
+    countsOf(job.kind).failed += 1;
+    if (!failedSaid.has(job.kind)) {
+      failedSaid.add(job.kind);
+      log(`plune: could not upload a ${KINDS[job.kind].label} (${why}) \u2014 its result is reported without it.`);
+    }
+  }
+  function failedToBucket(job, code) {
+    countsOf(job.kind).failed += 1;
+    if (codesSaid.has(code)) return;
+    codesSaid.add(code);
+    log(`plune: "${job.name}" not uploaded to your bucket (${code}) \u2014 its result is reported without it.`);
+  }
+  function refusedHere(job, size) {
+    if (job.kind === "screenshot") {
+      if (!SCREENSHOT_TYPES.has(job.type)) return "type";
+      if (size > SCREENSHOT_BYTES) return "size";
+    }
+    if (job.kind === "text" && size > TEXT_BYTES) return "textSize";
+    return void 0;
+  }
+  async function uploadDirect(job, size) {
     const { kind } = job;
-    const { label, bytes: ceiling, size } = KINDS[kind];
+    if (kind === "file") return skip(kind, job.name, "noStorage");
+    const { bytes: ceiling, size: tooBig } = KINDS[kind];
+    if (size > ceiling) return skip(kind, job.name, tooBig);
     let bytes;
     if (job.body !== void 0) bytes = job.body;
-    else if (job.path === void 0) return skip(kind, job.name, "missing");
     else {
       try {
-        if ((await import_node_fs3.promises.stat(job.path)).size > ceiling) return skip(kind, job.name, size);
-        bytes = await import_node_fs3.promises.readFile(job.path);
+        bytes = await import_node_fs4.promises.readFile(job.path);
       } catch {
         return skip(kind, job.name, "missing");
       }
@@ -752,32 +874,96 @@ async function startRun(passed, declared) {
       bytes,
       job.type
     );
-    const counts = countsOf(kind);
-    if (out.ok) {
-      counts.uploaded += 1;
-      return;
+    if (out.ok) countsOf(kind).uploaded += 1;
+    else failed(job, out.detail || out.kind);
+  }
+  async function uploadToBucket(job, size, first) {
+    const source = job.body !== void 0 ? { body: job.body } : { path: job.path, size };
+    let link = first;
+    for (let renewed = false; ; ) {
+      const put = await client.put(link.url, link.headers, source);
+      if (put.ok) break;
+      if (put.status !== 403 || renewed) return failedToBucket(job, put.code);
+      renewed = true;
+      const again = await ask(job, size);
+      if (!again.ok) return failedToBucket(job, codeOf(again));
+      const fresh = linkOf(again.body?.files?.[0]);
+      if (fresh === void 0) return failedToBucket(job, "bad_answer");
+      link = fresh;
+    }
+    const done2 = await client.post(`/v1/files/${encodeURIComponent(link.id)}/complete`, {});
+    if (!done2.ok) return failedToBucket(job, codeOf(done2));
+    countsOf(job.kind).uploaded += 1;
+  }
+  let free = UPLOADS_AT_ONCE;
+  const waiting = [];
+  async function gated(work) {
+    if (free === 0) await new Promise((resolve2) => waiting.push(resolve2));
+    else free -= 1;
+    try {
+      return await work();
+    } finally {
+      const next = waiting.shift();
+      if (next !== void 0) next();
+      else free += 1;
+    }
+  }
+  async function plan(job) {
+    const { kind } = job;
+    let size;
+    if (job.body !== void 0) size = job.body.length;
+    else if (job.path === void 0) return void skip(kind, job.name, "missing");
+    else {
+      try {
+        size = (await import_node_fs4.promises.stat(job.path)).size;
+      } catch {
+        return void skip(kind, job.name, "missing");
+      }
     }
-    counts.failed += 1;
-    if (counts.failed === 1) {
-      log(`plune: could not upload a ${label} (${out.detail || out.kind}) \u2014 its result is reported without it.`);
+    if (size === 0) return void skip(kind, job.name, "empty");
+    const direct = () => {
+      if (kind === "file") return void skip(kind, job.name, "noStorage");
+      const roomKey = `${job.id}/${kind}`;
+      const left = rooms.get(roomKey) ?? KINDS[kind].room;
+      if (left === 0) return void skip(kind, job.name, KINDS[kind].limit);
+      rooms.set(roomKey, left - 1);
+      return () => uploadDirect(job, size);
+    };
+    if (uploadsMissing) return direct();
+    const out = await gated(() => ask(job, size));
+    if (!out.ok) {
+      if (out.status === 404 && out.detail === "" && out.code === void 0) {
+        uploadsMissing = true;
+        return direct();
+      }
+      if (out.code !== void 0) failedToBucket(job, out.code);
+      else failed(job, out.detail || out.kind);
+      return void 0;
     }
+    const item = out.body?.files?.[0];
+    if (item?.skipped === "no_storage") return void skip(kind, job.name, refusedHere(job, size) ?? "noStorage");
+    if (item?.direct === true) return direct();
+    const link = linkOf(item);
+    if (link === void 0) return void failed(job, "bad_answer");
+    if (!bucketSeen) {
+      bucketSeen = true;
+      log(BUCKET_FOUND);
+    }
+    return () => uploadToBucket(job, size, link);
   }
   async function upload(items, filesByKey) {
     if (filesByKey.size === 0 || !Array.isArray(items)) return;
     const jobs = [];
     for (const item of items) {
       if (item?.status !== "accepted" || typeof item.id !== "string" || typeof item.resultKey !== "string") continue;
-      const room = { screenshot: KINDS.screenshot.room, text: KINDS.text.room };
       for (const file of filesByKey.get(item.resultKey) ?? []) {
         const type = mediaTypeOf(file.contentType) ?? (file.path === void 0 ? void 0 : TYPE_BY_EXTENSION[(0, import_node_path3.extname)(file.path).toLowerCase()]);
-        const kind = type === void 0 ? void 0 : kindOf(type);
-        if (type === void 0 || kind === void 0 || kind === "screenshot" && file.path === void 0) continue;
+        if (type === void 0 || type === METADATA_TYPE2) continue;
+        const kind = kindOf(type);
+        if (kind !== "text" && file.path === void 0) continue;
         const name = nameOf(file);
         if (file.name.startsWith("_")) skip(kind, name, "hidden");
-        else if (kind === "screenshot" && !SCREENSHOT_TYPES.has(type)) skip(kind, name, "type");
-        else if (room[kind] === 0) skip(kind, name, KINDS[kind].limit);
         else {
-          room[kind] -= 1;
           jobs.push({
             id: item.id,
             kind,
@@ -789,10 +975,16 @@ async function startRun(passed, declared) {
         }
       }
     }
-    let next = 0;
+    const byResult = /* @__PURE__ */ new Map();
+    for (const job of jobs) byResult.set(job.id, [...byResult.get(job.id) ?? [], job]);
     await Promise.all(
-      Array.from({ length: Math.min(UPLOADS_AT_ONCE, jobs.length) }, async () => {
-        while (next < jobs.length) await uploadOne(jobs[next++]);
+      [...byResult.values()].map(async (group) => {
+        const work = [];
+        for (const job of group) {
+          const act = await plan(job);
+          if (act !== void 0) work.push(gated(act));
+        }
+        await Promise.all(work);
       })
     );
   }
@@ -870,8 +1062,20 @@ async function startRun(passed, declared) {
     if (stats.unresolved > 0) parts.push(`${stats.unresolved} with no matching test case`);
     if (stats.offered > 0) parts.push(`${stats.offered} offered for review`);
     if (stats.created > 0) parts.push(`${stats.created} added as cases (trusted source)`);
-    for (const said of [tally(stats.screenshots, "screenshot"), tally(stats.textFiles, "text file")]) {
-      if (said !== void 0) parts.push(said);
+    const kinds = [stats.screenshots, stats.textFiles, stats.otherFiles];
+    const sum = (what) => kinds.reduce((n, counts) => n + counts[what], 0);
+    if (bucketSeen) {
+      const other = sum("skipped") - noStorage;
+      parts.push(
+        `${sum("uploaded")} file(s) uploaded to your bucket` + (noStorage > 0 ? `, ${noStorage} skipped (no bucket connected)` : "") + (other > 0 ? `, ${other} skipped` : "") + (sum("failed") > 0 ? `, ${sum("failed")} failed to upload` : "")
+      );
+    } else {
+      for (const said of [tally(stats.screenshots, "screenshot"), tally(stats.textFiles, "text file")]) {
+        if (said !== void 0) parts.push(said);
+      }
+      const other = stats.otherFiles;
+      if (other.skipped > 0) parts.push(`${other.skipped} file(s) not stored (no bucket connected)`);
+      if (other.failed > 0) parts.push(`${other.failed} file(s) failed to upload`);
     }
     if (stats.deferred > 0) parts.push(`${stats.deferred} not delivered \u2014 written to ${fallbackPath}`);
     if (shortened.size > 0) parts.push(`${shortened.size} test name(s) shortened to fit a key`);

package/dist/reporter-core.d.cts

@@ -287,6 +287,15 @@ interface RunStats extends SubmitCounts {
         skipped: number;
         failed: number;
     };
+    /**
+     * Every other file (a trace, a video, a page): only a project's bucket takes them (plune-ai/plune#946), so
+     * without one they are counted as skipped. With one, the summary adds all three kinds up.
+     */
+    otherFiles: {
+        uploaded: number;
+        skipped: number;
+        failed: number;
+    };
 }
 /** Everything the core needs to talk to a deployment. */
 interface ReporterConfig {
@@ -532,6 +541,26 @@ type ClientOutcome<T> = {
     kind: ClientFailureKind;
     status: number | null;
     detail: string;
+    code?: string;
+};
+/** What a PUT to a bucket carries: a file on disk, streamed at a length known beforehand, or bytes in memory. */
+type PutSource = {
+    path: string;
+    size: number;
+} | {
+    body: Buffer;
+};
+/**
+ * How a PUT ended. Never a URL, never a message: the link is a write key to someone's bucket, and the
+ * errors of the transports (`getaddrinfo ENOTFOUND <host>`, `no answer from <origin>`) name the host. All
+ * that survives is a status and a short code.
+ */
+type PutOutcome = {
+    ok: true;
+} | {
+    ok: false;
+    status: number | null;
+    code: string;
 };
 interface ClientOptions {
     apiUrl: string;
@@ -554,6 +583,12 @@ interface PlatformClient {
      * a proxy error page that echoes the request would put a token in a CI log.
      */
     del<T>(path: string): Promise<ClientOutcome<T>>;
+    /**
+     * The bytes to a short-lived link of the customer's bucket (plune-ai/plune#946): exactly the headers the
+     * link came with, no token of ours. Network failures and 5xx wait and try again, up to three times; a 403
+     * (the link has expired) comes back at once, for the caller to ask for a new one.
+     */
+    put(url: string, headers: Record<string, string>, source: PutSource): Promise<PutOutcome>;
 }
 declare function createClient(opts: ClientOptions): PlatformClient;
 

package/dist/reporter-core.d.ts

@@ -287,6 +287,15 @@ interface RunStats extends SubmitCounts {
         skipped: number;
         failed: number;
     };
+    /**
+     * Every other file (a trace, a video, a page): only a project's bucket takes them (plune-ai/plune#946), so
+     * without one they are counted as skipped. With one, the summary adds all three kinds up.
+     */
+    otherFiles: {
+        uploaded: number;
+        skipped: number;
+        failed: number;
+    };
 }
 /** Everything the core needs to talk to a deployment. */
 interface ReporterConfig {
@@ -532,6 +541,26 @@ type ClientOutcome<T> = {
     kind: ClientFailureKind;
     status: number | null;
     detail: string;
+    code?: string;
+};
+/** What a PUT to a bucket carries: a file on disk, streamed at a length known beforehand, or bytes in memory. */
+type PutSource = {
+    path: string;
+    size: number;
+} | {
+    body: Buffer;
+};
+/**
+ * How a PUT ended. Never a URL, never a message: the link is a write key to someone's bucket, and the
+ * errors of the transports (`getaddrinfo ENOTFOUND <host>`, `no answer from <origin>`) name the host. All
+ * that survives is a status and a short code.
+ */
+type PutOutcome = {
+    ok: true;
+} | {
+    ok: false;
+    status: number | null;
+    code: string;
 };
 interface ClientOptions {
     apiUrl: string;
@@ -554,6 +583,12 @@ interface PlatformClient {
      * a proxy error page that echoes the request would put a token in a CI log.
      */
     del<T>(path: string): Promise<ClientOutcome<T>>;
+    /**
+     * The bytes to a short-lived link of the customer's bucket (plune-ai/plune#946): exactly the headers the
+     * link came with, no token of ours. Network failures and 5xx wait and try again, up to three times; a 403
+     * (the link has expired) comes back at once, for the caller to ask for a new one.
+     */
+    put(url: string, headers: Record<string, string>, source: PutSource): Promise<PutOutcome>;
 }
 declare function createClient(opts: ClientOptions): PlatformClient;