@hostr/cli 0.1.2 → 0.1.4

package/dist/cli.js

@@ -12,6 +12,14 @@ var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require
   if (typeof require !== "undefined") return require.apply(this, arguments);
   throw Error('Dynamic require of "' + x + '" is not supported');
 });
+var __esm = (fn, res, err) => function __init() {
+  if (err) throw err[0];
+  try {
+    return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+  } catch (e) {
+    throw err = [e], e;
+  }
+};
 var __commonJS = (cb, mod) => function __require2() {
   try {
     return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
@@ -19,6 +27,10 @@ var __commonJS = (cb, mod) => function __require2() {
     throw mod = 0, e;
   }
 };
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
 var __copyProps = (to, from, except, desc) => {
   if (from && typeof from === "object" || typeof from === "function") {
     for (let key of __getOwnPropNames(from))
@@ -3462,6 +3474,344 @@ var require_commander = __commonJS({
   }
 });
 
+// ../upload/src/api/client.ts
+async function req(fetchFn, endpoint, bearer, path, init2 = {}) {
+  const url = `${trimEndpoint(endpoint)}${path}`;
+  const headers = { authorization: `Bearer ${bearer}` };
+  let body;
+  if (init2.body !== void 0) {
+    headers["content-type"] = "application/json";
+    body = JSON.stringify(init2.body);
+  }
+  let res;
+  try {
+    res = await fetchFn(url, { method: init2.method ?? "GET", headers, body });
+  } catch {
+    throw new NetworkError();
+  }
+  const text = await res.text();
+  const data = text ? JSON.parse(text) : {};
+  if (!res.ok) {
+    const code = data && typeof data === "object" && typeof data.error === "string" ? data.error : void 0;
+    throw new ApiError2(res.status, code);
+  }
+  return data;
+}
+async function createUploadSession(opts, fetchFn = fetch) {
+  const { endpoint, apiKey, ...body } = opts;
+  return req(fetchFn, endpoint, apiKey, "/v1/uploads", { method: "POST", body });
+}
+function mintUploadToken(opts, fetchFn = fetch) {
+  const { endpoint, apiKey, assetId, tokenTtlSec } = opts;
+  return req(fetchFn, endpoint, apiKey, `/v1/uploads/${assetId}/token`, {
+    method: "POST",
+    body: tokenTtlSec === void 0 ? {} : { tokenTtlSec }
+  });
+}
+var ApiError2, NetworkError, trimEndpoint, HostrApi;
+var init_client = __esm({
+  "../upload/src/api/client.ts"() {
+    "use strict";
+    ApiError2 = class extends Error {
+      status;
+      code;
+      constructor(status, code) {
+        super(code ? `hostr api error ${status}: ${code}` : `hostr api error ${status}`);
+        this.name = "ApiError";
+        this.status = status;
+        this.code = code;
+      }
+    };
+    NetworkError = class extends Error {
+      constructor(message = "network error") {
+        super(message);
+        this.name = "NetworkError";
+      }
+    };
+    trimEndpoint = (endpoint) => endpoint.replace(/\/$/, "");
+    HostrApi = class {
+      #endpoint;
+      #bearer;
+      #fetch;
+      constructor(endpoint, bearer, fetchFn = fetch) {
+        this.#endpoint = endpoint;
+        this.#bearer = bearer;
+        this.#fetch = fetchFn;
+      }
+      setBearer(bearer) {
+        this.#bearer = bearer;
+      }
+      getUpload(assetId) {
+        return req(this.#fetch, this.#endpoint, this.#bearer, `/v1/uploads/${assetId}`);
+      }
+      presignParts(assetId, partNumbers, expiresIn) {
+        return req(this.#fetch, this.#endpoint, this.#bearer, `/v1/uploads/${assetId}/parts`, {
+          method: "POST",
+          body: expiresIn === void 0 ? { partNumbers } : { partNumbers, expiresIn }
+        });
+      }
+      complete(assetId, body) {
+        return req(this.#fetch, this.#endpoint, this.#bearer, `/v1/uploads/${assetId}/complete`, {
+          method: "POST",
+          body
+        });
+      }
+      async abort(assetId) {
+        await req(this.#fetch, this.#endpoint, this.#bearer, `/v1/uploads/${assetId}`, { method: "DELETE" });
+      }
+    };
+  }
+});
+
+// src/gui.ts
+var gui_exports = {};
+__export(gui_exports, {
+  uploadGui: () => uploadGui
+});
+import { createServer } from "node:http";
+import { randomBytes } from "node:crypto";
+import { spawn } from "node:child_process";
+async function uploadGui(ctx) {
+  const secret = Array.from(randomBytes(16), (b) => b.toString(16).padStart(2, "0")).join("");
+  const server = createServer(async (req2, res) => {
+    const url = new URL(req2.url ?? "/", "http://localhost");
+    const send = (status, body, type = "application/json") => {
+      res.writeHead(status, { "content-type": type, "cache-control": "no-store" });
+      res.end(body);
+    };
+    try {
+      if (url.pathname === "/" && url.searchParams.get("s") === secret)
+        return send(200, page(ctx.apiBase, secret), "text/html; charset=utf-8");
+      if (url.searchParams.get("s") !== secret) return send(403, '{"error":"forbidden"}');
+      if (url.pathname === "/api/session" && req2.method === "POST") {
+        const chunks = [];
+        for await (const c of req2) chunks.push(c);
+        const { filename, size, contentType } = JSON.parse(Buffer.concat(chunks).toString());
+        const s = await createUploadSession({ endpoint: ctx.apiBase, apiKey: ctx.key, filename, size, contentType });
+        return send(200, JSON.stringify(s));
+      }
+      if (url.pathname.startsWith("/api/status/") && req2.method === "GET") {
+        const a = await ctx.client.asset(url.pathname.slice("/api/status/".length));
+        return send(200, JSON.stringify(a));
+      }
+      if (url.pathname.startsWith("/api/playback/") && req2.method === "POST") {
+        try {
+          const t = await ctx.client.assetTokens(url.pathname.slice("/api/playback/".length));
+          return send(200, JSON.stringify(t));
+        } catch {
+          return send(200, JSON.stringify({ unavailable: true }));
+        }
+      }
+      return send(404, '{"error":"not_found"}');
+    } catch (e) {
+      return send(500, JSON.stringify({ error: String(e.message).slice(0, 300) }));
+    }
+  });
+  const server6 = createServer((req2, res) => server.emit("request", req2, res));
+  const listen = (srv, host, port2) => new Promise((resolve) => {
+    const onErr = (e) => {
+      srv.removeAllListeners("listening");
+      resolve(e.code ?? "ERR");
+    };
+    srv.once("error", onErr);
+    srv.listen(port2, host, () => {
+      srv.removeListener("error", onErr);
+      resolve(null);
+    });
+  });
+  let port = 0;
+  for (const candidate of CORS_PORTS) {
+    const e4 = await listen(server, "127.0.0.1", candidate);
+    if (e4) continue;
+    const e6 = await listen(server6, "::1", candidate);
+    if (e6 && e6 !== "EADDRNOTAVAIL") {
+      await new Promise((r) => server.close(() => r(null)));
+      continue;
+    }
+    port = candidate;
+    break;
+  }
+  if (!port) throw new Error("no free port among the CORS-allowed set (3000-3005, 5173, 8899)");
+  const addr = `http://localhost:${port}/?s=${secret}`;
+  process.stderr.write(`upload page ready: ${addr}
+(drop a video in the browser; Ctrl+C here when done)
+`);
+  const opener = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+  spawn(opener, [addr], { stdio: "ignore", detached: true }).unref();
+  await new Promise(() => {
+  });
+}
+var CORS_PORTS, page;
+var init_gui = __esm({
+  "src/gui.ts"() {
+    "use strict";
+    init_client();
+    CORS_PORTS = [3005, 3004, 3003, 3002, 3001, 5173, 3e3, 8899];
+    page = (apiBase, secret) => `<!doctype html>
+<meta charset="utf-8"><title>hostr upload</title>
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<style>
+  :root { --bg:#fdf6e3; --ink:#111; --surface:#fff; --accent:#2b4cff; --ok:#0a8f4d; --danger:#e0301e; }
+  * { box-sizing:border-box; }
+  body { background:var(--bg); color:var(--ink); font:15px/1.5 system-ui, sans-serif; margin:0; padding:40px 20px; }
+  main { max-width:640px; margin:0 auto; }
+  h1 { font-size:22px; font-weight:800; margin:0 0 4px; }
+  .sub { color:#5a5a5a; font-size:13px; margin:0 0 24px; }
+  #drop { background:var(--surface); border:2px dashed var(--ink); border-radius:6px; padding:56px 24px;
+          text-align:center; font-weight:700; cursor:pointer; }
+  #drop.over { background:#eef1ff; border-style:solid; }
+  .card { background:var(--surface); border:2px solid var(--ink); border-radius:6px;
+          box-shadow:3px 3px 0 var(--ink); padding:16px; margin-top:16px; }
+  .bar { height:14px; border:2px solid var(--ink); border-radius:4px; overflow:hidden; margin:8px 0; }
+  .bar > div { height:100%; background:var(--accent); width:0%; transition:width .2s; }
+  .bar.enc > div { background:var(--ok); }
+  .mono { font-family:ui-monospace,monospace; font-size:12px; word-break:break-all; }
+  .err { color:var(--danger); font-weight:700; }
+  video { width:100%; border:2px solid var(--ink); border-radius:6px; margin-top:10px; background:#000; }
+  .hint { font-size:12px; color:#5a5a5a; }
+</style>
+<main>
+  <h1>hostr upload</h1>
+  <p class="sub">drop a video \u2014 it uploads straight to storage, transcodes, and plays back below</p>
+  <div id="drop">drop a video here<br><span class="hint">or click to choose</span></div>
+  <input id="file" type="file" accept="video/*,.mkv,.mov,.mp4,.webm" style="display:none">
+  <div id="jobs"></div>
+</main>
+<script>
+const API = ${JSON.stringify(apiBase)}, S = ${JSON.stringify(secret)};
+const drop = document.getElementById('drop'), input = document.getElementById('file');
+drop.onclick = () => input.click();
+input.onchange = () => [...input.files].forEach(go);
+['dragover','dragenter'].forEach(e => drop.addEventListener(e, ev => { ev.preventDefault(); drop.classList.add('over'); }));
+['dragleave','drop'].forEach(e => drop.addEventListener(e, ev => { ev.preventDefault(); drop.classList.remove('over'); }));
+drop.addEventListener('drop', ev => [...ev.dataTransfer.files].forEach(go));
+
+// A bar that fills with no numbers beside it is indistinguishable from a hung
+// one \u2014 which is exactly how a 10-minute encode read before these existed.
+// Every long phase gets elapsed, rate, and a remaining estimate.
+const mmss = s => Math.floor(s / 60) + ':' + String(Math.floor(s % 60)).padStart(2, '0');
+const left = s => s >= 90 ? '~' + Math.round(s / 60) + 'm left' : '~' + Math.max(1, Math.round(s)) + 's left';
+const size = b => b >= 1e9 ? (b / 1e9).toFixed(2) + ' GB' : (b / 1e6).toFixed(0) + ' MB';
+
+const local = (p, o) => fetch(p + '?s=' + S, o).then(r => r.json());
+const api = (p, tok, body) => fetch(API + p, { method:'POST',
+  headers:{ authorization:'Bearer ' + tok, 'content-type':'application/json' },
+  body: JSON.stringify(body ?? {}) }).then(async r => { const j = await r.json(); if (!r.ok) throw new Error(j.error || r.status); return j; });
+
+async function go(file) {
+  const el = document.createElement('div'); el.className = 'card'; document.getElementById('jobs').prepend(el);
+  el.innerHTML = '<b>' + file.name + '</b><div class="bar"><div></div></div><div class="st">creating session\u2026</div>';
+  const bar = el.querySelector('.bar > div'), st = el.querySelector('.st');
+  try {
+    const sess = await local('/api/session', { method:'POST', body: JSON.stringify({
+      filename: file.name, size: file.size, contentType: file.type || 'application/octet-stream' }) });
+    if (sess.error) throw new Error(sess.error);
+    const { assetId, uploadToken, partSize, expectedParts } = sess;
+
+    // Part URLs in batches of 100 (the API's cap), uploads 4 at a time via
+    // XHR \u2014 fetch has no upload progress.
+    const done = new Array(expectedParts).fill(0);
+    // Cumulative average rather than an instantaneous rate: it smooths a
+    // fluctuating connection instead of flickering between wild numbers, and
+    // over a multi-minute upload it converges on the honest figure anyway.
+    let upStart = 0;
+    const paint = () => {
+      const sent = done.reduce((a,b)=>a+b,0);
+      bar.style.width = (sent / file.size * 100).toFixed(1) + '%';
+      // Freeze once every byte is sent. R2 can take a beat to acknowledge the
+      // last part, and paint() keeps firing through it \u2014 with sent pinned at
+      // file.size and elapsed still growing, the rate visibly decays and reads
+      // as a dying connection at the exact moment the upload succeeded.
+      // 'finalizing\u2026' takes over from here anyway.
+      if (!upStart || !sent || sent >= file.size) return;
+      const el = (Date.now() - upStart) / 1000;
+      const rate = sent / el;
+      st.textContent = 'uploading \xB7 ' + size(sent) + ' / ' + size(file.size)
+        + ' \xB7 ' + (rate / 1e6).toFixed(1) + ' MB/s'
+        + (rate > 0 ? ' \xB7 ' + left((file.size - sent) / rate) : '');
+    };
+    let urls = [];
+    for (let b = 1; b <= expectedParts; b += 100) {
+      const nums = []; for (let n = b; n < b + 100 && n <= expectedParts; n++) nums.push(n);
+      urls = urls.concat((await api('/v1/uploads/' + assetId + '/parts', uploadToken, { partNumbers: nums })).urls);
+    }
+    st.textContent = 'uploading\u2026';
+    upStart = Date.now();
+    let idx = 0;
+    await Promise.all(Array.from({ length: 4 }, async function worker() {
+      while (idx < urls.length) {
+        const u = urls[idx++];
+        const start = (u.partNumber - 1) * partSize;
+        const blob = file.slice(start, Math.min(start + partSize, file.size));
+        await new Promise((res, rej) => {
+          const x = new XMLHttpRequest();
+          x.open('PUT', u.url);
+          x.upload.onprogress = e => { done[u.partNumber - 1] = e.loaded; paint(); };
+          x.onload = () => x.status < 300 ? (done[u.partNumber - 1] = blob.size, paint(), res()) : rej(new Error('part ' + u.partNumber + ' -> ' + x.status));
+          x.onerror = () => rej(new Error('part ' + u.partNumber + ' network error'));
+          x.send(blob);
+        });
+      }
+    }));
+    st.textContent = 'finalizing\u2026';
+    await api('/v1/uploads/' + assetId + '/complete', uploadToken);
+
+    el.insertAdjacentHTML('beforeend', '<div class="bar enc"><div></div></div>');
+    const enc = el.querySelectorAll('.bar > div')[1];
+    st.textContent = 'queued \xB7 waking the encoder\u2026';
+    for (;;) {
+      await new Promise(r => setTimeout(r, 2500));
+      const a = await local('/api/status/' + assetId);
+      const p = a.progress;
+      if (p?.totalSec) enc.style.width = (p.encodedSec / p.totalSec * 100).toFixed(1) + '%';
+      if (a.status === 'ready') break;
+      if (a.status === 'failed') throw new Error('transcode failed: ' + (a.error || 'unknown'));
+      // Three distinct waits, and conflating them is what made this read as a
+      // hang: the machine scales to zero so it may be booting; then it pulls
+      // the source out of R2 and probes it; only then does progress exist.
+      // Until the first progress post there is nothing to put in the bar, so
+      // the label has to carry the state instead.
+      st.textContent =
+        p?.totalSec
+          ? 'transcoding \xB7 ' + mmss(p.encodedSec) + ' / ' + mmss(p.totalSec)
+            + (p.speed ? ' \xB7 ' + p.speed.toFixed(2) + '\xD7' : '')
+            // speed is optional on the wire (the API forwards it only when it
+            // is a number), so the estimate goes rather than reading NaN.
+            + (p.speed > 0 ? ' \xB7 ' + left((p.totalSec - p.encodedSec) / p.speed) : '')
+          : a.status === 'processing' ? 'transcoding \xB7 reading the source\u2026'
+          : 'queued \xB7 waking the encoder\u2026';
+    }
+    enc.style.width = '100%';
+
+    const t = await local('/api/playback/' + assetId, { method: 'POST' });
+    const mediaHost = API.replace('api.', 'stream.');
+    if (t.unavailable) {
+      st.innerHTML = 'ready \u2014 asset <span class="mono">' + assetId + '</span><br><span class="hint">key lacks full scope, so no preview token \u2014 mint one server-side to play</span>';
+      return;
+    }
+    const src = mediaHost + '/' + assetId + '.m3u8?token=' + encodeURIComponent(t.playback);
+    st.innerHTML = 'ready \u2014 asset <span class="mono">' + assetId + '</span>';
+    const v = document.createElement('video');
+    v.controls = true; v.playsInline = true;
+    v.poster = mediaHost + '/' + assetId + '/thumbnail.jpg?token=' + encodeURIComponent(t.thumbnail);
+    el.appendChild(v);
+    if (v.canPlayType('application/vnd.apple.mpegurl')) v.src = src;
+    else {
+      const s = document.createElement('script');
+      s.src = 'https://cdn.jsdelivr.net/npm/hls.js@1';
+      s.onload = () => { const h = new Hls(); h.loadSource(src); h.attachMedia(v); };
+      document.head.appendChild(s);
+    }
+    el.insertAdjacentHTML('beforeend',
+      '<p class="hint">playback URL (token expires in 1h \u2014 mint per view in production):</p><p class="mono">' + src + '</p>');
+  } catch (e) {
+    st.innerHTML = '<span class="err">' + e.message + '</span>';
+  }
+}
+</script>`;
+  }
+});
+
 // ../../node_modules/.pnpm/commander@14.0.3/node_modules/commander/esm.mjs
 var import_index = __toESM(require_commander(), 1);
 var {
@@ -3536,9 +3886,9 @@ function makeClient(opts) {
       method,
       headers: {
         authorization: `Bearer ${opts.key}`,
-        ...o.body !== void 0 ? { "content-type": "application/json" } : {}
+        ...o.rawBody ? { "content-type": o.rawBody.contentType } : o.body !== void 0 ? { "content-type": "application/json" } : {}
       },
-      ...o.body !== void 0 ? { body: JSON.stringify(o.body) } : {}
+      ...o.rawBody ? { body: o.rawBody.text } : o.body !== void 0 ? { body: JSON.stringify(o.body) } : {}
     });
     const body = await res.json().catch(() => ({}));
     if (!res.ok) throw new ApiError(res.status, body);
@@ -3549,6 +3899,13 @@ function makeClient(opts) {
     assets: (params = {}) => req2("GET", "/v1/assets", { params }),
     asset: (id) => req2("GET", `/v1/assets/${id}`),
     assetTokens: (id, body = {}) => req2("POST", `/v1/assets/${id}/tokens`, { body }),
+    subtitles: (id) => req2("GET", `/v1/assets/${id}/subtitles`),
+    subtitleSet: (id, lang, vtt, o = {}) => req2(
+      "PUT",
+      `/v1/assets/${id}/subtitles/${lang}`,
+      { params: { name: o.name, default: o.default ? "true" : void 0 }, rawBody: { text: vtt, contentType: "text/vtt" } }
+    ),
+    subtitleDelete: (id, lang) => req2("DELETE", `/v1/assets/${id}/subtitles/${lang}`),
     assetDelete: (id) => req2("DELETE", `/v1/assets/${id}`),
     usage: (params = {}) => req2("GET", "/v1/usage", { params }),
     events: (params = {}) => req2("GET", "/v1/events", { params }),
@@ -3771,90 +4128,8 @@ function partSizeOf(s, n) {
   return s.partSize;
 }
 
-// ../upload/src/api/client.ts
-var ApiError2 = class extends Error {
-  status;
-  code;
-  constructor(status, code) {
-    super(code ? `hostr api error ${status}: ${code}` : `hostr api error ${status}`);
-    this.name = "ApiError";
-    this.status = status;
-    this.code = code;
-  }
-};
-var NetworkError = class extends Error {
-  constructor(message = "network error") {
-    super(message);
-    this.name = "NetworkError";
-  }
-};
-var trimEndpoint = (endpoint) => endpoint.replace(/\/$/, "");
-async function req(fetchFn, endpoint, bearer, path, init2 = {}) {
-  const url = `${trimEndpoint(endpoint)}${path}`;
-  const headers = { authorization: `Bearer ${bearer}` };
-  let body;
-  if (init2.body !== void 0) {
-    headers["content-type"] = "application/json";
-    body = JSON.stringify(init2.body);
-  }
-  let res;
-  try {
-    res = await fetchFn(url, { method: init2.method ?? "GET", headers, body });
-  } catch {
-    throw new NetworkError();
-  }
-  const text = await res.text();
-  const data = text ? JSON.parse(text) : {};
-  if (!res.ok) {
-    const code = data && typeof data === "object" && typeof data.error === "string" ? data.error : void 0;
-    throw new ApiError2(res.status, code);
-  }
-  return data;
-}
-var HostrApi = class {
-  #endpoint;
-  #bearer;
-  #fetch;
-  constructor(endpoint, bearer, fetchFn = fetch) {
-    this.#endpoint = endpoint;
-    this.#bearer = bearer;
-    this.#fetch = fetchFn;
-  }
-  setBearer(bearer) {
-    this.#bearer = bearer;
-  }
-  getUpload(assetId) {
-    return req(this.#fetch, this.#endpoint, this.#bearer, `/v1/uploads/${assetId}`);
-  }
-  presignParts(assetId, partNumbers, expiresIn) {
-    return req(this.#fetch, this.#endpoint, this.#bearer, `/v1/uploads/${assetId}/parts`, {
-      method: "POST",
-      body: expiresIn === void 0 ? { partNumbers } : { partNumbers, expiresIn }
-    });
-  }
-  complete(assetId, body) {
-    return req(this.#fetch, this.#endpoint, this.#bearer, `/v1/uploads/${assetId}/complete`, {
-      method: "POST",
-      body
-    });
-  }
-  async abort(assetId) {
-    await req(this.#fetch, this.#endpoint, this.#bearer, `/v1/uploads/${assetId}`, { method: "DELETE" });
-  }
-};
-async function createUploadSession(opts, fetchFn = fetch) {
-  const { endpoint, apiKey, ...body } = opts;
-  return req(fetchFn, endpoint, apiKey, "/v1/uploads", { method: "POST", body });
-}
-function mintUploadToken(opts, fetchFn = fetch) {
-  const { endpoint, apiKey, assetId, tokenTtlSec } = opts;
-  return req(fetchFn, endpoint, apiKey, `/v1/uploads/${assetId}/token`, {
-    method: "POST",
-    body: tokenTtlSec === void 0 ? {} : { tokenTtlSec }
-  });
-}
-
 // ../upload/src/core/retry.ts
+init_client();
 var RETRY_BUDGET = 6;
 function classifyPut(res, err) {
   if (err instanceof NetworkError) return "network";
@@ -3924,6 +4199,9 @@ function computeProgress(i) {
   return progress;
 }
 
+// ../upload/src/core/engine.ts
+init_client();
+
 // ../upload/src/hash/hex.ts
 var HEX = "0123456789abcdef";
 function bytesToHex(b) {
@@ -4670,6 +4948,7 @@ var UploadEngine = class {
 };
 
 // ../upload/src/core/upload.ts
+init_client();
 var realClock = { now: () => Date.now(), sleep: (ms) => new Promise((res) => setTimeout(res, ms)) };
 async function buildUpload(opts) {
   const clock = opts.clock ?? realClock;
@@ -4739,6 +5018,7 @@ var NodeMd5 = class {
 var nodeHasher = { md5: () => new NodeMd5() };
 
 // ../upload/src/node/index.ts
+init_client();
 async function nodeFileSource(path) {
   const handle = await open(path, "r");
   const stat2 = await handle.stat();
@@ -4825,9 +5105,9 @@ async function tailLoop(opts) {
   let cursor = opts.after;
   const poll = async () => {
     try {
-      const page = await opts.fetchPage(cursor);
-      if (page.items.length) opts.onBatch(page.items);
-      cursor = page.nextCursor ?? cursor;
+      const page2 = await opts.fetchPage(cursor);
+      if (page2.items.length) opts.onBatch(page2.items);
+      cursor = page2.nextCursor ?? cursor;
       return true;
     } catch {
       return false;
@@ -4858,14 +5138,14 @@ var MIME = {
 };
 var mimeOf = (file) => MIME[(/\.([A-Za-z0-9]+)$/.exec(file)?.[1] ?? "").toLowerCase()] ?? "application/octet-stream";
 async function assetsList(ctx, opts) {
-  const page = await ctx.client.assets({
+  const page2 = await ctx.client.assets({
     status: opts.status,
     cursor: opts.cursor,
     limit: opts.limit ? Number(opts.limit) : void 0
   });
   ctx.out.print(
     table(
-      page.items.map((a) => ({ ...a, bytes: fmtBytes(a.bytes), createdAt: fmtWhen(a.createdAt) })),
+      page2.items.map((a) => ({ ...a, bytes: fmtBytes(a.bytes), createdAt: fmtWhen(a.createdAt) })),
       [
         { key: "assetId", label: "ASSET" },
         { key: "status", label: "STATUS" },
@@ -4874,9 +5154,9 @@ async function assetsList(ctx, opts) {
         { key: "durationSec", label: "DURATION" },
         { key: "createdAt", label: "CREATED" }
       ]
-    ) + (page.nextCursor ? `
-(more: --cursor ${page.nextCursor})` : ""),
-    page
+    ) + (page2.nextCursor ? `
+(more: --cursor ${page2.nextCursor})` : ""),
+    page2
   );
 }
 async function assetsGet(ctx, id) {
@@ -4902,6 +5182,23 @@ async function assetsDelete(ctx, id) {
   const r = await ctx.client.assetDelete(id);
   ctx.out.print(`deleted ${r.assetId} (${r.objectsDeleted} objects purged)`, r);
 }
+async function subtitlesList(ctx, id) {
+  const r = await ctx.client.subtitles(id);
+  ctx.out.print(
+    r.tracks.length ? r.tracks.map((t) => `${t.lang.padEnd(8)}${t.name.padEnd(24)}${t.default ? "default" : ""}`).join("\n") : "(no subtitle tracks)",
+    r
+  );
+}
+async function subtitlesSet(ctx, id, file, opts) {
+  const { readFile: readFile4 } = await import("node:fs/promises");
+  const vtt = await readFile4(file, "utf8");
+  const r = await ctx.client.subtitleSet(id, opts.lang, vtt, { name: opts.name, default: opts.default });
+  ctx.out.print(`subtitle ${r.lang} ("${r.name}") attached to ${r.assetId}${r.default ? " as default" : ""}`, r);
+}
+async function subtitlesRm(ctx, id, lang) {
+  const r = await ctx.client.subtitleDelete(id, lang);
+  ctx.out.print(`subtitle ${lang} removed from ${r.assetId}`, r);
+}
 async function tail(ctx, opts) {
   const fmt = (e) => `${fmtWhen(e.createdAt)}  ${e.type.padEnd(16)}  ${e.assetId ?? "-"}`;
   await tailLoop({
@@ -4915,6 +5212,10 @@ async function tail(ctx, opts) {
 }
 async function upload(ctx, file, opts) {
   if (!ctx.key) fail(ctx.out, new Error(NOT_LOGGED_IN));
+  if (!file) {
+    const { uploadGui: uploadGui2 } = await Promise.resolve().then(() => (init_gui(), gui_exports));
+    return uploadGui2({ apiBase: ctx.apiBase, key: ctx.key, client: ctx.client });
+  }
   const size = (await stat(file).catch(() => null))?.size;
   if (!size) fail(ctx.out, new Error(`cannot read ${file}`));
   const apiKey = ctx.key;
@@ -4966,7 +5267,7 @@ import { mkdir as mkdir3, readFile as readFile3, writeFile as writeFile3 } from
 import { join as join3 } from "node:path";
 
 // ../../docs/integrate.md
-var integrate_default = '# hostr \u2014 integration guide\n\nhostr is self-hosted video infrastructure: resumable upload \u2192 transcode \u2192\nHLS delivery, with signed playback URLs. This document is the complete,\nself-contained integration reference. It is written to be executed by a\ncoding agent; every command has a `--json` mode and every flow is\nverifiable from the terminal.\n\n```\nAPI base    https://api.hostr.sh                         (override: HOSTR_API_BASE)\nMedia host  https://stream.hostr.sh                 (playback URLs are built on this)\nDocs        GET {API base}/llms.txt  \xB7  GET {API base}/llms-full.txt (this file)\n```\n\n## 0. TL;DR for an integrating agent\n\n```bash\nnpx @hostr/cli login --key $HOSTR_API_KEY   # validate + save the key (or export HOSTR_API_KEY)\nnpx @hostr/cli init                          # write docs/hostr.md + AGENTS.md section + .env.example entries\nnpx @hostr/cli upload demo.mp4 --wait --json # -> { assetId, status: "ready", ... }\nnpx @hostr/cli webhooks set https://yourapp.example/hostr-webhook --json  # -> { secret: "whsec_..." } ONCE\nnpx @hostr/cli tail --follow                 # watch the event log live\n```\n\nThen in your app: store `assetId`/`playbackId` per video, mint playback\ntokens server-side (\xA76), and hand players\n`{Media host}/{playbackId}.m3u8?token=\u2026`. Verify webhooks with the snippet\nin \xA75. That is the whole integration.\n\n## 1. Authentication\n\nEvery API call sends `Authorization: Bearer <credential>`. There are two\ncredential kinds an integrator sees:\n\n- **API key** \u2014 `hostr_sk_live_\u2026`, minted per account in the hostr\n  dashboard or via `POST /v1/keys` / `npx @hostr/cli keys create`. Scoped:\n  - `read` \u2014 GETs only (status, listing, usage, events)\n  - `upload` \u2014 read + the upload lifecycle\n  - `full` \u2014 everything, including playback-token minting and key management\n  Keys are hashed at rest; the plaintext is shown exactly once at mint.\n  Rotation = create new + revoke old (`DELETE /v1/keys/:id`); revocation\n  takes effect within ~60 s. **Keep keys server-side.** Never ship one in a\n  browser or mobile app.\n- **Upload token** \u2014 short-lived HMAC scoped to a single upload\n  (`uploadToken` in the create-upload response). This is the only\n  credential an untrusted client (browser/mobile) should ever hold: it can\n  drive that one upload and nothing else.\n\nAuth errors: `401 {"error":"unauthorized"}` (bad/missing/revoked key, or a\nresource you don\'t own \u2014 hostr does not reveal which),\n`403 {"error":"insufficient_scope","need":"upload"}`,\n`403 {"error":"account_suspended"}`,\n`503 {"error":"control_plane_unavailable"}` (transient \u2014 retry with backoff;\nin-flight uploads with upload tokens are unaffected).\n\n## 2. Upload\n\nThree ways, strongest first:\n\n### 2a. CLI (recommended \u2014 resumable, integrity-checked)\n\n```bash\nnpx @hostr/cli upload path/to/video.mp4 --json           # returns when bytes are verified in R2\nnpx @hostr/cli upload path/to/video.mp4 --wait --json    # returns when transcode is ready/failed\n```\n\nOutput: `{ "assetId": "\u2026", "status": "queued"|"ready", "bytes": n, "etag": "\u2026", "sha256": "\u2026" }`.\nThe CLI wraps hostr\'s upload SDK: chunked multipart direct to storage,\nresume after crash/restart (server-authoritative \u2014 it asks storage which\nparts landed), retry with backoff, and three-layer integrity verification.\nExit code 1 + JSON on stderr on failure.\n\n### 2b. Raw HTTP (any language, no SDK)\n\n```\nPOST /v1/uploads                     {"filename":"a.mp4","size":<bytes>,"contentType":"video/mp4"}\n  -> 201 { assetId, partSize, expectedParts, uploadToken, tokenExpiresAt, key, uploadId }\n     (forward ONLY assetId/uploadToken/partSize/expectedParts/tokenExpiresAt to untrusted clients)\n\nPOST /v1/uploads/:id/parts           {"partNumbers":[1,2,...]}        (\u2264100 per call)\n  -> { urls: [{partNumber, url}], expiresIn }\nPUT  <each presigned url>            body = that part\'s bytes; capture the ETag response header\n\nGET  /v1/uploads/:id                 -> { status, uploadedParts, parts, bytesUploaded }   (resume)\nPOST /v1/uploads/:id/complete        {"sha256":"<hex of whole file>"}  (sha256 optional)\n  -> { assetId, status: "uploaded"|"queued", bytes, etag }\nDELETE /v1/uploads/:id               abort\nPOST /v1/uploads/:id/token           re-mint the upload token (API key with upload scope)\n```\n\nRules: every part is `partSize` bytes except the last; `size` must be\nexact \u2014 completion verifies both part count and total bytes against what\nactually landed and returns `409 incomplete_upload` (with the missing part\nnumbers) or `409 size_mismatch` otherwise. Completion is idempotent \u2014 a\ncrashed client retries it safely. Uploads are quota-gated:\n`403 {"error":"quota_uploads_daily"|"quota_assets"|"quota_storage","limit":n}`.\n\n### 2c. Browser/mobile clients\n\nCreate the upload server-side (2b), hand the client only\n`{assetId, uploadToken, partSize, expectedParts}`, and let it PUT parts\ndirectly to the presigned URLs \u2014 upload bytes never touch your servers.\n(A browser needs the storage bucket to allow your origin via CORS \u2014 if\npart PUTs stall at 0% with network-looking errors, that\'s the cause.)\n\n## 3. Asset lifecycle\n\n`uploading \u2192 uploaded \u2192 queued \u2192 processing \u2192 ready | failed` (plus\n`aborted`). Poll `GET /v1/assets/:id` (`read` scope) or \u2014 better \u2014 use\nwebhooks (\xA75). While `processing`, the asset carries live transcode\nprogress \u2014 `progress: { encodedSec, totalSec, speed }` (speed is the\nencode multiple of realtime; the field is null/absent outside\n`processing`) \u2014 so a UI can show a real percentage instead of a spinner. `GET /v1/assets?limit=&status=&cursor=` lists your assets\nnewest-first with keyset pagination (`nextCursor`).\n\nWhen `ready`, the asset record and the `video.ready` event both carry\n`playbackId` (equals `assetId` today \u2014 store it as its own field) and\n`durationSec`.\n\n## 4. Account, usage, keys\n\n```\nGET  /v1/account        -> { accountId, name, plan, limits, usage }      (read)\nGET  /v1/usage?from&to  -> { days: [{day, uploads, bytesUploaded, encodedSeconds}] }  (read)\nPOST /v1/keys           {"name":"ci","scopes":["upload"]} -> { key: "hostr_sk_live_..." } ONCE  (full)\nGET  /v1/keys           -> metadata only, never hashes                    (full)\nDELETE /v1/keys/:id     -> { revoked: true }                              (full)\n```\n\n## 5. Webhooks + the event log\n\nConfigure one endpoint per account:\n\n```\nPUT  /v1/webhooks   {"url":"https://yourapp.example/hostr-webhook"}      (full)\n  -> { url, enabled, secret: "whsec_..." }        # secret returned ONLY when generated, ONLY once\nGET  /v1/webhooks   -> { url, enabled, createdAt }                        # never the secret\nDELETE /v1/webhooks -> disables (delivery history retained)\n```\n\nEvents \u2014 body `{ id, type, createdAt, data }`; `id` is the durable event\nrow\'s id (dedupe on it):\n\n| type             | fired when                             | data highlights                          |\n|------------------|----------------------------------------|------------------------------------------|\n| `upload.created` | multipart session opened               | `assetId`, `filename`, `declaredSize`    |\n| `video.uploaded` | bytes verified in storage, transcode queued | `assetId`, `bytes`, `etag`, `sha256?` |\n| `video.ready`    | HLS renditions live                    | `assetId`, `playbackId`, `durationSec?`  |\n| `video.errored`  | transcode failed                       | `assetId`, `error` (always present)      |\n| `video.deleted`  | asset erased; playback over            | `assetId`                                |\n\nEndpoint URLs: both `https` and `http` are accepted, including private\naddresses \u2014 hostr does not currently block internal ranges, so a local\nreceiver works in development exactly like production.\n\nEvery delivery carries `hostr-signature`, a comma-separated list currently\ncontaining `t=<unix-seconds>` and `v1=<hex>` where\n`v1 = HMAC-SHA256(secret, "<t>.<rawBody>")` \u2014 the Stripe scheme. Parse it\nas a list (future fields may be added); verify before trusting\n(constant-time compare, bounded timestamp):\n\n```js\nimport { createHmac, timingSafeEqual } from \'node:crypto\';\n\nexport function verifyHostrWebhook(secret, header, rawBody, toleranceSec = 300) {\n  const m = /^t=(\\d+),v1=([0-9a-f]{64})$/.exec(header ?? \'\');\n  if (!m) return false;\n  if (Math.abs(Date.now() / 1000 - Number(m[1])) > toleranceSec) return false;\n  const expected = createHmac(\'sha256\', secret).update(`${m[1]}.${rawBody}`).digest(\'hex\');\n  return expected.length === m[2].length &&\n    timingSafeEqual(Buffer.from(expected), Buffer.from(m[2]));\n}\n// Use the RAW request body bytes \u2014 parse JSON only after verification.\n```\n\nDelivery is at-least-once (3 attempts with backoff, each recorded). The\nwebhook is the wake-up signal; the **durable event log** is the ledger:\n\n```\nGET  /v1/events?after=<cursor>&limit=&type=   ascending; reuse nextCursor verbatim   (read)\nGET  /v1/events?order=desc&limit=1            newest first (e.g. the latest event)   (read)\nPOST /v1/events/:id/redeliver                 replay any stored event                (full)\n```\n\n`npx @hostr/cli tail --follow` polls this for you; `npx @hostr/cli webhooks test`\nredelivers the newest event to prove your endpoint end-to-end. Respond\n`2xx` fast (do the work async) \u2014 anything else is retried.\n\n## 6. Playback\n\nPlayback is token-gated. Mint per view, server-side, with a `full` key:\n\n```\nPOST /v1/assets/:id/tokens    {"ttlSec":3600,"viewerId":"user-123"}      (optional body)\n  -> { playback, thumbnail, storyboard, expiresAt }                       (expiresAt in ms)\nnpx @hostr/cli assets token <assetId> --json                                   (CLI equivalent)\n```\n\nMinting works any time after the asset exists (it 404s only for unknown\nassets); the stream itself returns 404 until the asset is `ready` \u2014 gate\nyour UI on `video.ready` / asset status, not on whether minting succeeds.\n\nBuild the URL and hand it to any HLS player:\n\n```\nhttps://stream.hostr.sh/{playbackId}.m3u8?token={playback}\n```\n\n- Use hls.js in browsers without native HLS; Safari/iOS play it natively.\n- The token is checked once at the master playlist; the stream then works\n  for the whole viewing session (segment credentials are handled\n  internally). Default TTL 1 h \u2014 it only needs to be valid when playback\n  *starts*.\n- `viewerId` enables per-viewer concurrency observation.\n- **Non-browser user agents are rejected** (`403 blocked_user_agent`):\n  curl/wget/ffmpeg/vlc UAs are blocked as a casual-ripping speed bump. For\n  server-side smoke tests send a browser-like `User-Agent`.\n- Signed URLs are not DRM: they stop link-sharing and hotlinking, not an\n  entitled viewer recording their screen.\n- `DELETE /v1/assets/:id` erases an asset for good: source and renditions\n  are purged from storage, the storage quota is freed, and `video.deleted`\n  is emitted. Deletion is idempotent (repeat calls return `deleted`\n  again). New playback tokens stop minting immediately; tokens already\n  issued can replay edge-cached segments for at most a few hours until\n  they expire. There is no undelete.\n\nThe token bundle also covers the poster image and scrub previews \u2014 same\nhost, same query-token shape, each URL taking its matching token from the\nmint response:\n\n```\nhttps://stream.hostr.sh/{playbackId}/thumbnail.jpg?token={thumbnail}\nhttps://stream.hostr.sh/{playbackId}/storyboard.vtt?token={storyboard}\n```\n\nThe storyboard is a standard "thumbnails" WebVTT track (cues point into a\ntiled sprite with `#xywh=` fragments) \u2014 hand it to mux-player\'s\n`storyboard-src`, media-chrome\'s preview track, or any player that consumes\nthat convention; the sprite URLs inside the VTT are pre-signed for you.\nPlayers treat the track as optional: for assets encoded before storyboards\nexisted the URL 404s and scrubbing simply shows no preview.\n\n## 7. Error handling summary\n\n| status | error                        | meaning / action |\n|--------|------------------------------|------------------|\n| 401    | `unauthorized`               | bad/revoked key, or not your resource \u2014 check key + assetId |\n| 403    | `insufficient_scope`         | key scope too low; `need` names the required scope |\n| 403    | `quota_*`                    | account limit hit; `limit` is the ceiling |\n| 403    | `account_suspended`          | contact the operator |\n| 409    | `incomplete_upload`          | parts missing (`missing` lists them) \u2014 upload them, re-complete |\n| 409    | `size_mismatch`              | declared size \u2260 bytes landed \u2014 abort and restart |\n| 409    | `not_uploading`              | upload already finished/aborted |\n| 413    | `file_too_large`             | raise `partSize` or split |\n| 503    | `control_plane_unavailable`  | transient \u2014 retry with backoff |\n| 500    | `signing_not_configured`     | operator-side: the playback signing key isn\'t loaded on this API deployment. Not your integration\'s fault and not retryable from the client \u2014 report it |\n\n## 8. Full route table\n\n| Method | Path | Scope | Purpose |\n|---|---|---|---|\n| POST | `/v1/uploads` | upload | create upload session |\n| GET | `/v1/uploads/:id` | upload* | status + landed parts (resume) |\n| POST | `/v1/uploads/:id/parts` | upload* | presigned part URLs |\n| POST | `/v1/uploads/:id/complete` | upload* | verify + finalize |\n| POST | `/v1/uploads/:id/token` | upload | re-mint upload token |\n| DELETE | `/v1/uploads/:id` | upload* | abort |\n| GET | `/v1/assets` | read | list own assets |\n| GET | `/v1/assets/:id` | read | asset record |\n| POST | `/v1/assets/:id/tokens` | full | playback credentials |\n| DELETE | `/v1/assets/:id` | full | erase asset: R2 purged, quota freed, `video.deleted` emitted |\n| GET | `/v1/account` | read | whoami: plan, limits, usage |\n| GET | `/v1/usage` | read | daily usage rows |\n| GET | `/v1/events` | read | durable event log (ascending tail; `order=desc` for newest-first) |\n| POST | `/v1/events/:id/redeliver` | full | replay a webhook |\n| GET/PUT/DELETE | `/v1/webhooks` | full | endpoint config |\n| POST/GET | `/v1/keys` | full | mint / list keys |\n| DELETE | `/v1/keys/:id` | full | revoke key |\n\n\\* also accepted: that upload\'s own `uploadToken`.\n\n## 9. CLI reference\n\n`npx @hostr/cli <cmd>` \u2014 every command takes `--json` (one JSON document on\nstdout; NDJSON for `tail --follow`; errors as JSON on stderr, exit 1).\nCredentials: `--key` flag > `HOSTR_API_KEY` env > saved profile\n(`hostr login`). API base: `--api` > `HOSTR_API_BASE` > profile > default.\n\n```\nlogin \xB7 whoami \xB7 usage \xB7 init\nkeys create|list|revoke\nwebhooks get|set|delete|test\nassets list|get \xB7 assets token <id> [--ttl <sec>] \xB7 upload <file> [--wait] \xB7 tail [--follow]\n```\n';
+var integrate_default = '# hostr \u2014 integration guide\n\nhostr is self-hosted video infrastructure: resumable upload \u2192 transcode \u2192\nHLS delivery, with signed playback URLs. This document is the complete,\nself-contained integration reference. It is written to be executed by a\ncoding agent; every command has a `--json` mode and every flow is\nverifiable from the terminal.\n\n```\nAPI base    https://api.hostr.sh                         (override: HOSTR_API_BASE)\nMedia host  https://stream.hostr.sh                 (playback URLs are built on this)\nDocs        GET {API base}/llms.txt  \xB7  GET {API base}/llms-full.txt (this file)\n```\n\n## 0. TL;DR for an integrating agent\n\n```bash\nnpx @hostr/cli login --key $HOSTR_API_KEY   # validate + save the key (or export HOSTR_API_KEY)\nnpx @hostr/cli init                          # write docs/hostr.md + AGENTS.md section + .env.example entries\nnpx @hostr/cli upload demo.mp4 --wait --json # -> { assetId, status: "ready", ... }\nnpx @hostr/cli upload                        # no file: opens a local drag-drop page in the browser\nnpx @hostr/cli webhooks set https://yourapp.example/hostr-webhook --json  # -> { secret: "whsec_..." } ONCE\nnpx @hostr/cli tail --follow                 # watch the event log live\n```\n\nThen in your app: store `assetId`/`playbackId` per video, mint playback\ntokens server-side (\xA76), and hand players\n`{Media host}/{playbackId}.m3u8?token=\u2026`. Verify webhooks with the snippet\nin \xA75. That is the whole integration.\n\n## 1. Authentication\n\nEvery API call sends `Authorization: Bearer <credential>`. There are two\ncredential kinds an integrator sees:\n\n- **API key** \u2014 `hostr_sk_live_\u2026`, minted per account in the hostr\n  dashboard or via `POST /v1/keys` / `npx @hostr/cli keys create`. Scoped:\n  - `read` \u2014 GETs only (status, listing, usage, events)\n  - `upload` \u2014 read + the upload lifecycle\n  - `full` \u2014 everything, including playback-token minting and key management\n  Keys are hashed at rest; the plaintext is shown exactly once at mint.\n  Rotation = create new + revoke old (`DELETE /v1/keys/:id`); revocation\n  takes effect within ~60 s. **Keep keys server-side.** Never ship one in a\n  browser or mobile app.\n- **Upload token** \u2014 short-lived HMAC scoped to a single upload\n  (`uploadToken` in the create-upload response). This is the only\n  credential an untrusted client (browser/mobile) should ever hold: it can\n  drive that one upload and nothing else.\n\nAuth errors: `401 {"error":"unauthorized"}` (bad/missing/revoked key, or a\nresource you don\'t own \u2014 hostr does not reveal which),\n`403 {"error":"insufficient_scope","need":"upload"}`,\n`403 {"error":"account_suspended"}`,\n`503 {"error":"control_plane_unavailable"}` (transient \u2014 retry with backoff;\nin-flight uploads with upload tokens are unaffected).\n\n## 2. Upload\n\nThree ways, strongest first:\n\n### 2a. CLI (recommended \u2014 resumable, integrity-checked)\n\n```bash\nnpx @hostr/cli upload path/to/video.mp4 --json           # returns when bytes are verified in R2\nnpx @hostr/cli upload path/to/video.mp4 --wait --json    # returns when transcode is ready/failed\n```\n\nOutput: `{ "assetId": "\u2026", "status": "queued"|"ready", "bytes": n, "etag": "\u2026", "sha256": "\u2026" }`.\nThe CLI wraps hostr\'s upload SDK: chunked multipart direct to storage,\nresume after crash/restart (server-authoritative \u2014 it asks storage which\nparts landed), retry with backoff, and three-layer integrity verification.\nExit code 1 + JSON on stderr on failure.\n\n### 2b. Raw HTTP (any language, no SDK)\n\n```\nPOST /v1/uploads                     {"filename":"a.mp4","size":<bytes>,"contentType":"video/mp4"}\n  -> 201 { assetId, partSize, expectedParts, uploadToken, tokenExpiresAt, key, uploadId }\n     (forward ONLY assetId/uploadToken/partSize/expectedParts/tokenExpiresAt to untrusted clients)\n\nPOST /v1/uploads/:id/parts           {"partNumbers":[1,2,...]}        (\u2264100 per call)\n  -> { urls: [{partNumber, url}], expiresIn }\nPUT  <each presigned url>            body = that part\'s bytes; capture the ETag response header\n\nGET  /v1/uploads/:id                 -> { status, uploadedParts, parts, bytesUploaded }   (resume)\nPOST /v1/uploads/:id/complete        {"sha256":"<hex of whole file>"}  (sha256 optional)\n  -> { assetId, status: "uploaded"|"queued", bytes, etag }\nDELETE /v1/uploads/:id               abort\nPOST /v1/uploads/:id/token           re-mint the upload token (API key with upload scope)\n```\n\nRules: every part is `partSize` bytes except the last; `size` must be\nexact \u2014 completion verifies both part count and total bytes against what\nactually landed and returns `409 incomplete_upload` (with the missing part\nnumbers) or `409 size_mismatch` otherwise. Completion is idempotent \u2014 a\ncrashed client retries it safely. Uploads are quota-gated:\n`403 {"error":"quota_uploads_daily"|"quota_assets"|"quota_storage","limit":n}`.\n\n### 2c. Browser/mobile clients\n\nCreate the upload server-side (2b), hand the client only\n`{assetId, uploadToken, partSize, expectedParts}`, and let it PUT parts\ndirectly to the presigned URLs \u2014 upload bytes never touch your servers.\n(A browser needs the storage bucket to allow your origin via CORS \u2014 if\npart PUTs stall at 0% with network-looking errors, that\'s the cause.)\n\n## 3. Asset lifecycle\n\n`uploading \u2192 uploaded \u2192 queued \u2192 processing \u2192 ready | failed` (plus\n`aborted`). Poll `GET /v1/assets/:id` (`read` scope) or \u2014 better \u2014 use\nwebhooks (\xA75). While `processing`, the asset carries live transcode\nprogress \u2014 `progress: { encodedSec, totalSec, speed }` (speed is the\nencode multiple of realtime; the field is null/absent outside\n`processing`) \u2014 so a UI can show a real percentage instead of a spinner. `GET /v1/assets?limit=&status=&cursor=` lists your assets\nnewest-first with keyset pagination (`nextCursor`).\n\nWhen `ready`, the asset record and the `video.ready` event both carry\n`playbackId` (equals `assetId` today \u2014 store it as its own field) and\n`durationSec`.\n\n## 4. Account, usage, keys\n\n```\nGET  /v1/account        -> { accountId, name, plan, limits, usage }      (read)\nGET  /v1/usage?from&to  -> { days: [{day, uploads, bytesUploaded, encodedSeconds}] }  (read)\nPOST /v1/keys           {"name":"ci","scopes":["upload"]} -> { key: "hostr_sk_live_..." } ONCE  (full)\nGET  /v1/keys           -> metadata only, never hashes                    (full)\nDELETE /v1/keys/:id     -> { revoked: true }                              (full)\n```\n\n## 5. Webhooks + the event log\n\nConfigure one endpoint per account:\n\n```\nPUT  /v1/webhooks   {"url":"https://yourapp.example/hostr-webhook"}      (full)\n  -> { url, enabled, secret: "whsec_..." }        # secret returned ONLY when generated, ONLY once\nGET  /v1/webhooks   -> { url, enabled, createdAt }                        # never the secret\nDELETE /v1/webhooks -> disables (delivery history retained)\n```\n\nEvents \u2014 body `{ id, type, createdAt, data }`; `id` is the durable event\nrow\'s id (dedupe on it):\n\n| type             | fired when                             | data highlights                          |\n|------------------|----------------------------------------|------------------------------------------|\n| `upload.created` | multipart session opened               | `assetId`, `filename`, `declaredSize`    |\n| `video.uploaded` | bytes verified in storage, transcode queued | `assetId`, `bytes`, `etag`, `sha256?` |\n| `video.ready`    | HLS renditions live                    | `assetId`, `playbackId`, `durationSec?`  |\n| `video.errored`  | transcode failed                       | `assetId`, `error` (always present)      |\n| `video.deleted`  | asset erased; playback over            | `assetId`                                |\n| `video.input.non_standard` | the source needed a judgement call | `assetId`, `input`, `findings[]`  |\n\n`video.input.non_standard` is advisory \u2014 the transcode proceeds normally and\na `video.ready` still follows. It fires at most once per asset, only when\nthere is something to say, and reports what the encoder had to assume:\n\n| finding code         | meaning                                                                 |\n|----------------------|-------------------------------------------------------------------------|\n| `hdr_tags_on_8bit`   | source carries HLG/PQ tags but is 8-bit. HDR is a 10-bit format, so the tag is stale \u2014 treated as SDR, pixels untouched |\n| `hdr_source`         | genuine 10-bit HDR. The ladder outputs 8-bit SDR; no tone mapping is applied |\n| `wide_gamut_tags`    | BT.2020 primaries without an HDR transfer; output is BT.709, colour not converted |\n| `variable_frame_rate`| container rate and measured rate disagree; normalised to CFR             |\n| `frame_rate_changed` | source rate was not a broadcast standard and was snapped to the nearest  |\n\n`data.input` carries the full probe: `videoCodec`, `pixFmt`, `bitDepth`,\n`width`, `height`, `declaredFps`, `averageFps`, `targetFps`,\n`isVariableFrameRate`, `colorSpace`, `colorTransfer`, `colorPrimaries`. The\nsame block is on the asset record as `input`, so it can be read back at any\ntime without replaying events.\n\nEndpoint URLs: both `https` and `http` are accepted, including private\naddresses \u2014 hostr does not currently block internal ranges, so a local\nreceiver works in development exactly like production.\n\nEvery delivery carries `hostr-signature`, a comma-separated list currently\ncontaining `t=<unix-seconds>` and `v1=<hex>` where\n`v1 = HMAC-SHA256(secret, "<t>.<rawBody>")` \u2014 the Stripe scheme. Parse it\nas a list (future fields may be added); verify before trusting\n(constant-time compare, bounded timestamp):\n\n```js\nimport { createHmac, timingSafeEqual } from \'node:crypto\';\n\nexport function verifyHostrWebhook(secret, header, rawBody, toleranceSec = 300) {\n  const m = /^t=(\\d+),v1=([0-9a-f]{64})$/.exec(header ?? \'\');\n  if (!m) return false;\n  if (Math.abs(Date.now() / 1000 - Number(m[1])) > toleranceSec) return false;\n  const expected = createHmac(\'sha256\', secret).update(`${m[1]}.${rawBody}`).digest(\'hex\');\n  return expected.length === m[2].length &&\n    timingSafeEqual(Buffer.from(expected), Buffer.from(m[2]));\n}\n// Use the RAW request body bytes \u2014 parse JSON only after verification.\n```\n\nDelivery is at-least-once (3 attempts with backoff, each recorded). The\nwebhook is the wake-up signal; the **durable event log** is the ledger:\n\n```\nGET  /v1/events?after=<cursor>&limit=&type=   ascending; reuse nextCursor verbatim   (read)\nGET  /v1/events?order=desc&limit=1            newest first (e.g. the latest event)   (read)\nPOST /v1/events/:id/redeliver                 replay any stored event                (full)\n```\n\n`npx @hostr/cli tail --follow` polls this for you; `npx @hostr/cli webhooks test`\nredelivers the newest event to prove your endpoint end-to-end. Respond\n`2xx` fast (do the work async) \u2014 anything else is retried.\n\n## 6. Playback\n\nPlayback is token-gated. Mint per view, server-side, with a `full` key:\n\n```\nPOST /v1/assets/:id/tokens    {"ttlSec":3600,"viewerId":"user-123"}      (optional body)\n  -> { playback, thumbnail, storyboard, expiresAt }                       (expiresAt in ms)\nnpx @hostr/cli assets token <assetId> --json                                   (CLI equivalent)\n```\n\nMinting works any time after the asset exists (it 404s only for unknown\nassets); the stream itself returns 404 until the asset is `ready` \u2014 gate\nyour UI on `video.ready` / asset status, not on whether minting succeeds.\n\nBuild the URL and hand it to any HLS player:\n\n```\nhttps://stream.hostr.sh/{playbackId}.m3u8?token={playback}\n```\n\n- Use hls.js in browsers without native HLS; Safari/iOS play it natively.\n- The token is checked once at the master playlist; the stream then works\n  for the whole viewing session (segment credentials are handled\n  internally). Default TTL 1 h \u2014 it only needs to be valid when playback\n  *starts*.\n- `viewerId` enables per-viewer concurrency observation.\n- **Non-browser user agents are rejected** (`403 blocked_user_agent`):\n  curl/wget/ffmpeg/vlc UAs are blocked as a casual-ripping speed bump. For\n  server-side smoke tests send a browser-like `User-Agent`.\n- Signed URLs are not DRM: they stop link-sharing and hotlinking, not an\n  entitled viewer recording their screen.\n- `DELETE /v1/assets/:id` erases an asset for good: source and renditions\n  are purged from storage, the storage quota is freed, and `video.deleted`\n  is emitted. Deletion is idempotent (repeat calls return `deleted`\n  again). New playback tokens stop minting immediately; tokens already\n  issued can replay edge-cached segments for at most a few hours until\n  they expire. There is no undelete.\n\nThe token bundle also covers the poster image and scrub previews \u2014 same\nhost, same query-token shape, each URL taking its matching token from the\nmint response:\n\n```\nhttps://stream.hostr.sh/{playbackId}/thumbnail.jpg?token={thumbnail}\nhttps://stream.hostr.sh/{playbackId}/storyboard.vtt?token={storyboard}\n```\n\nThe storyboard is a standard "thumbnails" WebVTT track (cues point into a\ntiled sprite with `#xywh=` fragments) \u2014 hand it to mux-player\'s\n`storyboard-src`, media-chrome\'s preview track, or any player that consumes\nthat convention; the sprite URLs inside the VTT are pre-signed for you.\nPlayers treat the track as optional: for assets encoded before storyboards\nexisted the URL 404s and scrubbing simply shows no preview.\n\n## 6b. Subtitles\n\nHuman-authored WebVTT tracks, attached any time after the asset is `ready`\n(409 `not_ready` before that \u2014 the playlist needs the duration):\n\n```\nPUT    /v1/assets/:id/subtitles/:lang?name=English&default=true    (body: raw WebVTT, upload scope)\nGET    /v1/assets/:id/subtitles                 -> { tracks: [{ lang, name, default, rev }] }\nDELETE /v1/assets/:id/subtitles/:lang\nnpx @hostr/cli subtitles set <assetId> subs.vtt --lang en --name English --default\n```\n\n- `:lang` is a BCP 47 tag (`en`, `pt-BR`); one track per tag, PUT replaces.\n- Tracks appear in the master playlist automatically (`EXT-X-MEDIA`\n  subtitles group) \u2014 the next master fetch after a PUT includes them, no\n  re-encode, no new playback URL. Players show them in the captions menu.\n- `default=true` demotes any previous default.\n- Replacements propagate on the next playback session; a viewer mid-session\n  keeps the track they started with.\n\n## 7. Error handling summary\n\n| status | error                        | meaning / action |\n|--------|------------------------------|------------------|\n| 401    | `unauthorized`               | bad/revoked key, or not your resource \u2014 check key + assetId |\n| 403    | `insufficient_scope`         | key scope too low; `need` names the required scope |\n| 403    | `quota_*`                    | account limit hit; `limit` is the ceiling |\n| 403    | `account_suspended`          | contact the operator |\n| 409    | `incomplete_upload`          | parts missing (`missing` lists them) \u2014 upload them, re-complete |\n| 409    | `size_mismatch`              | declared size \u2260 bytes landed \u2014 abort and restart |\n| 409    | `not_uploading`              | upload already finished/aborted |\n| 413    | `file_too_large`             | raise `partSize` or split |\n| 503    | `control_plane_unavailable`  | transient \u2014 retry with backoff |\n| 500    | `signing_not_configured`     | operator-side: the playback signing key isn\'t loaded on this API deployment. Not your integration\'s fault and not retryable from the client \u2014 report it |\n\n## 8. Full route table\n\n| Method | Path | Scope | Purpose |\n|---|---|---|---|\n| POST | `/v1/uploads` | upload | create upload session |\n| GET | `/v1/uploads/:id` | upload* | status + landed parts (resume) |\n| POST | `/v1/uploads/:id/parts` | upload* | presigned part URLs |\n| POST | `/v1/uploads/:id/complete` | upload* | verify + finalize |\n| POST | `/v1/uploads/:id/token` | upload | re-mint upload token |\n| DELETE | `/v1/uploads/:id` | upload* | abort |\n| GET | `/v1/assets` | read | list own assets |\n| GET | `/v1/assets/:id` | read | asset record |\n| POST | `/v1/assets/:id/tokens` | full | playback credentials |\n| DELETE | `/v1/assets/:id` | full | erase asset: R2 purged, quota freed, `video.deleted` emitted |\n| PUT | `/v1/assets/:id/subtitles/:lang` | upload | attach/replace WebVTT track |\n| GET | `/v1/assets/:id/subtitles` | read | list subtitle tracks |\n| DELETE | `/v1/assets/:id/subtitles/:lang` | upload | remove subtitle track |\n| GET | `/v1/account` | read | whoami: plan, limits, usage |\n| GET | `/v1/usage` | read | daily usage rows |\n| GET | `/v1/events` | read | durable event log (ascending tail; `order=desc` for newest-first) |\n| POST | `/v1/events/:id/redeliver` | full | replay a webhook |\n| GET/PUT/DELETE | `/v1/webhooks` | full | endpoint config |\n| POST/GET | `/v1/keys` | full | mint / list keys |\n| DELETE | `/v1/keys/:id` | full | revoke key |\n\n\\* also accepted: that upload\'s own `uploadToken`.\n\n## 9. CLI reference\n\n`npx @hostr/cli <cmd>` \u2014 every command takes `--json` (one JSON document on\nstdout; NDJSON for `tail --follow`; errors as JSON on stderr, exit 1).\nCredentials: `--key` flag > `HOSTR_API_KEY` env > saved profile\n(`hostr login`). API base: `--api` > `HOSTR_API_BASE` > profile > default.\n\n```\nlogin \xB7 whoami \xB7 usage \xB7 init\nkeys create|list|revoke\nwebhooks get|set|delete|test\nassets list|get \xB7 assets token <id> [--ttl <sec>] \xB7 upload <file> [--wait] \xB7 tail [--follow]\n```\n';
 
 // src/init-content.ts
 var BEGIN = "<!-- hostr:begin -->";
@@ -5055,7 +5356,7 @@ async function init(opts) {
 }
 
 // src/cli.ts
-var program2 = new Command("hostr").description("hostr \u2014 self-hosted video infrastructure (upload, transcode, HLS delivery)").version("0.1.2").option("--key <key>", "API key (overrides HOSTR_API_KEY and the saved profile)").option("--api <url>", "API base URL (overrides HOSTR_API_BASE and the saved profile)").option("--json", "machine-readable output: one JSON document (NDJSON for tail --follow)");
+var program2 = new Command("hostr").description("hostr \u2014 self-hosted video infrastructure (upload, transcode, HLS delivery)").version("0.1.3").option("--key <key>", "API key (overrides HOSTR_API_KEY and the saved profile)").option("--api <url>", "API base URL (overrides HOSTR_API_BASE and the saved profile)").option("--json", "machine-readable output: one JSON document (NDJSON for tail --follow)");
 var globals = () => program2.opts();
 var run = (fn) => async (...args) => {
   const g = globals();
@@ -5084,6 +5385,10 @@ webhooks.command("get").action(run(webhooksGet));
 webhooks.command("set <url>").option("--secret <secret>", "bring your own whsec (default: generated, shown once)").action(run((ctx, url, opts) => webhooksSet(ctx, url, opts)));
 webhooks.command("delete").action(run(webhooksDelete));
 webhooks.command("test").description("redeliver the newest stored event to your endpoint").action(run(webhooksTest));
+var subtitles = program2.command("subtitles").description("subtitle tracks (WebVTT)");
+subtitles.command("list <assetId>").action(run((ctx, id) => subtitlesList(ctx, id)));
+subtitles.command("set <assetId> <file>").description("attach or replace a WebVTT track (requires upload scope)").requiredOption("--lang <tag>", "BCP 47 language tag, e.g. en or pt-BR").option("--name <label>", "menu label; defaults to the lang tag").option("--default", "make this the default track").action(run((ctx, id, file, opts) => subtitlesSet(ctx, id, file, opts)));
+subtitles.command("rm <assetId> <lang>").action(run((ctx, id, lang) => subtitlesRm(ctx, id, lang)));
 var assets = program2.command("assets").description("asset listing and status");
 assets.command("list").option("--status <status>").option("--limit <n>").option("--cursor <cursor>").action(run(assetsList));
 assets.command("get <id>").action(run((ctx, id) => assetsGet(ctx, id)));
@@ -5093,7 +5398,7 @@ program2.command("tail").description("event log (durable; ascending). One page b
 program2.command("init").description("make this repo agent-ready: docs/hostr.md + AGENTS.md section + .env.example entries").option("--dir <dir>", "target directory (default: cwd)").action(async (opts) => {
   await init({ ...globals(), ...opts });
 });
-program2.command("upload <file>").description("resumable multipart upload via the hostr SDK").option("--content-type <type>").option("--wait", "block until transcode reaches ready/failed").action(run((ctx, file, opts) => upload(ctx, file, opts)));
+program2.command("upload [file]").description("upload a video \u2014 with no file, opens a local drag-drop page in the browser").option("--content-type <type>").option("--wait", "block until transcode reaches ready/failed (file mode)").action(run((ctx, file, opts) => upload(ctx, file, opts)));
 program2.parseAsync().catch((e) => {
   console.error(`error: ${e?.message ?? e}`);
   process.exit(1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hostr/cli",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "CLI for hostr \u2014 self-hosted video infrastructure (upload, transcode, HLS delivery)",
   "license": "MIT",
   "type": "module",