@mega-yfue/eufy-sdk 0.2.0-beta.14 → 0.2.0-beta.15

package/dist/index.js

@@ -217,18 +217,33 @@ BLOCKED_ADDRESSES.addAddress("::1", "ipv6");
 BLOCKED_ADDRESSES.addSubnet("fc00::", 7, "ipv6");
 BLOCKED_ADDRESSES.addSubnet("fe80::", 10, "ipv6");
 var MediaDownloadError = class extends Error {
+  mediaFailure;
+  status;
+  constructor(message, mediaFailure, status) {
+    super(message);
+    this.name = "MediaDownloadError";
+    this.mediaFailure = mediaFailure;
+    if (status !== void 0)
+      this.status = status;
+  }
 };
+function mediaFailureError(message, reason, cause) {
+  const error = new MediaDownloadError(message, reason);
+  if (cause !== void 0)
+    error.cause = cause;
+  return error;
+}
 var MediaDownloadAuthenticationError = class extends Error {
 };
-function allowedMediaUrl(value, hostPattern) {
+function allowedMediaUrl(value, hostPattern, reason) {
   let url;
   try {
     url = new URL(value);
   } catch {
-    throw new MediaDownloadError("Media download rejected");
+    throw new MediaDownloadError("Media download rejected", reason);
   }
   if (url.protocol !== "https:" || url.username !== "" || url.password !== "" || url.port !== "" || isIP(url.hostname) !== 0 || !hostPattern.test(url.hostname)) {
-    throw new MediaDownloadError("Media download rejected");
+    throw new MediaDownloadError("Media download rejected", reason);
   }
   return url;
 }
@@ -243,7 +258,7 @@ async function assertPublicResolution(url, resolveHost2, signal) {
   try {
     addresses = await Promise.race([resolveHost2(url.hostname), aborted]);
   } catch {
-    throw new MediaDownloadError("Media download rejected");
+    throw new MediaDownloadError("Media download rejected", "address-not-public");
   } finally {
     signal.removeEventListener("abort", onAbort);
   }
@@ -251,14 +266,14 @@ async function assertPublicResolution(url, resolveHost2, signal) {
     const type = family === 6 ? "ipv6" : family === 4 ? "ipv4" : void 0;
     return type === void 0 || BLOCKED_ADDRESSES.check(address, type);
   })) {
-    throw new MediaDownloadError("Media download rejected");
+    throw new MediaDownloadError("Media download rejected", "address-not-public");
   }
 }
 var resolveHost = (hostname) => lookup(hostname, { all: true, verbatim: true });
 async function readMediaBody(response) {
   const contentLength = response.headers.get("content-length");
   if (contentLength && /^\d+$/.test(contentLength) && BigInt(contentLength) > BigInt(MEDIA_DOWNLOAD_MAX_BYTES)) {
-    throw new MediaDownloadError("Media download rejected");
+    throw new MediaDownloadError("Media download rejected", "too-large");
   }
   if (!response.body)
     return Buffer.alloc(0);
@@ -272,14 +287,14 @@ async function readMediaBody(response) {
     bytes2 += value.byteLength;
     if (bytes2 > MEDIA_DOWNLOAD_MAX_BYTES) {
       void reader2.cancel().catch(() => void 0);
-      throw new MediaDownloadError("Media download rejected");
+      throw new MediaDownloadError("Media download rejected", "too-large");
     }
     chunks.push(value);
   }
   return Buffer.concat(chunks, bytes2);
 }
 async function downloadMediaResource(url, authenticatedHeaders, fetchImpl = fetch, resolver = resolveHost) {
-  const original = allowedMediaUrl(url, EUFY_MEDIA_HOST);
+  const original = allowedMediaUrl(url, EUFY_MEDIA_HOST, "url-not-allowed");
   const controller = new AbortController();
   const timeout = setTimeout(() => controller.abort(), MEDIA_DOWNLOAD_TIMEOUT_MS);
   try {
@@ -292,31 +307,33 @@ async function downloadMediaResource(url, authenticatedHeaders, fetchImpl = fetc
     if (originalResponse.status >= 300 && originalResponse.status < 400) {
       const location = originalResponse.headers.get("location");
       if (!location)
-        throw new MediaDownloadError("Media download rejected");
-      const target = allowedMediaUrl(location, EUFY_OBJECT_HOST);
+        throw new MediaDownloadError("Media download rejected", "redirect-not-allowed");
+      const target = allowedMediaUrl(location, EUFY_OBJECT_HOST, "redirect-not-allowed");
       await assertPublicResolution(target, resolver, controller.signal);
       const redirectedResponse = await fetchImpl(target, { redirect: "manual", signal: controller.signal });
       if (redirectedResponse.status >= 300 && redirectedResponse.status < 400) {
-        throw new MediaDownloadError("Media download rejected");
+        throw new MediaDownloadError("Media download rejected", "redirect-not-allowed");
+      }
+      if (redirectedResponse.status !== 200) {
+        throw new MediaDownloadError("Media download failed", "http-status", redirectedResponse.status);
       }
-      if (redirectedResponse.status !== 200)
-        throw new MediaDownloadError("Media download failed");
       return await readMediaBody(redirectedResponse);
     }
     if (originalResponse.status === 401 || originalResponse.status === 403) {
       throw new MediaDownloadAuthenticationError("Media authentication failed");
     }
-    if (originalResponse.status !== 200)
-      throw new MediaDownloadError("Media download failed");
+    if (originalResponse.status !== 200) {
+      throw new MediaDownloadError("Media download failed", "http-status", originalResponse.status);
+    }
     return await readMediaBody(originalResponse);
   } catch (error) {
     if (controller.signal.aborted)
-      throw new MediaDownloadError("Media download timed out");
+      throw new MediaDownloadError("Media download timed out", "timeout");
     if (error instanceof MediaDownloadAuthenticationError)
       throw error;
     if (error instanceof MediaDownloadError)
       throw error;
-    throw new MediaDownloadError("Media download failed");
+    throw new MediaDownloadError("Media download failed", "network");
   } finally {
     clearTimeout(timeout);
   }
@@ -375,8 +392,228 @@ function randomUserAgent(seed, model) {
 // dist/transport/http/decodeImageV1.js
 import { createDecipheriv as createDecipheriv2, createHash as createHash2 } from "node:crypto";
 
+// dist/transport/http/jpeg-scan.js
+var DHT = 196;
+var SOS = 218;
+var DRI = 221;
+var RST_FIRST = 208;
+var RST_LAST = 215;
+var LUMA_SAMPLING = { 0: [1, 1], 1: [2, 1], 2: [2, 2] };
+var ScanEnd = class extends Error {
+};
+function readHuffmanTables(segment, into) {
+  const end = 2 + (segment[2] << 8 | segment[3]);
+  let at = 4;
+  while (at < end) {
+    const id = segment[at];
+    const counts = segment.subarray(at + 1, at + 17);
+    let total = 0;
+    for (const count2 of counts)
+      total += count2;
+    const values = segment.slice(at + 17, at + 17 + total);
+    const minCode = new Int32Array(17);
+    const maxCode = new Int32Array(17).fill(-1);
+    const valPtr = new Int32Array(17);
+    let code = 0;
+    let index = 0;
+    for (let length = 1; length <= 16; length++) {
+      const count2 = counts[length - 1];
+      if (count2 > 0) {
+        valPtr[length] = index;
+        minCode[length] = code;
+        code += count2;
+        index += count2;
+        maxCode[length] = code - 1;
+      }
+      code <<= 1;
+    }
+    into.set(id, { minCode, maxCode, valPtr, values });
+    at += 17 + total;
+  }
+}
+var BitReader = class {
+  /** Byte offset of the next byte to read. */
+  position;
+  bits = 0;
+  count = 0;
+  /** Set when the reader stepped over a restart marker — the caller resets its DC predictors. */
+  restarted = false;
+  data;
+  constructor(data, start) {
+    this.data = data;
+    this.position = start;
+  }
+  /** The offset the last whole byte ended at — what "how much of the scan did this consume" reads. */
+  get consumed() {
+    return this.position;
+  }
+  readBit() {
+    if (this.count === 0) {
+      if (this.position >= this.data.length)
+        throw new ScanEnd("out of data");
+      let byte = this.data[this.position++];
+      if (byte === 255) {
+        const next = this.data[this.position];
+        if (next === 0) {
+          this.position++;
+        } else if (next !== void 0 && next >= RST_FIRST && next <= RST_LAST) {
+          this.position++;
+          this.restarted = true;
+          if (this.position >= this.data.length)
+            throw new ScanEnd("out of data");
+          byte = this.data[this.position++];
+          if (byte === 255)
+            throw new ScanEnd("marker after restart");
+        } else {
+          this.position--;
+          throw new ScanEnd("marker");
+        }
+      }
+      this.bits = byte;
+      this.count = 8;
+    }
+    this.count--;
+    return this.bits >> this.count & 1;
+  }
+  /** Read `length` bits, most significant first. */
+  readBits(length) {
+    let value = 0;
+    for (let i = 0; i < length; i++)
+      value = value << 1 | this.readBit();
+    return value;
+  }
+  /** Drop the current byte's remaining bits — what a restart interval boundary does. */
+  align() {
+    this.count = 0;
+  }
+};
+function decodeHuffman(reader2, table) {
+  let code = reader2.readBit();
+  for (let length = 1; length <= 16; length++) {
+    if (table.maxCode[length] >= 0 && code <= table.maxCode[length]) {
+      return table.values[table.valPtr[length] + code - table.minCode[length]];
+    }
+    code = code << 1 | reader2.readBit();
+  }
+  throw new ScanEnd("no huffman code of any length");
+}
+function extend(value, length) {
+  return value < 1 << length - 1 ? value - (1 << length) + 1 : value;
+}
+function decodeBlock(reader2, component) {
+  const dcLength = decodeHuffman(reader2, component.dc);
+  if (dcLength > 16)
+    throw new ScanEnd("dc magnitude out of range");
+  component.pred += dcLength === 0 ? 0 : extend(reader2.readBits(dcLength), dcLength);
+  let k = 1;
+  while (k < 64) {
+    const rs = decodeHuffman(reader2, component.ac);
+    const size = rs & 15;
+    const run = rs >> 4;
+    if (size === 0) {
+      if (run !== 15)
+        break;
+      k += 16;
+    } else {
+      k += run;
+      if (k > 63)
+        throw new ScanEnd("ac coefficient index out of range");
+      reader2.readBits(size);
+      k++;
+    }
+  }
+  return component.pred;
+}
+function scanEntropy(tail, subsampling, extraTables) {
+  const tables = /* @__PURE__ */ new Map();
+  for (const segment of extraTables)
+    readHuffmanTables(segment, tables);
+  let at = 0;
+  let restartInterval = 0;
+  let scanStart = -1;
+  let assignments = [];
+  while (at + 3 < tail.length) {
+    if (tail[at] !== 255)
+      return null;
+    const marker = tail[at + 1];
+    const length = tail[at + 2] << 8 | tail[at + 3];
+    if (marker === DHT) {
+      readHuffmanTables(tail.subarray(at, at + 2 + length), tables);
+    } else if (marker === DRI) {
+      restartInterval = tail[at + 4] << 8 | tail[at + 5];
+    } else if (marker === SOS) {
+      const count2 = tail[at + 4];
+      assignments = [];
+      for (let i = 0; i < count2; i++) {
+        const id = tail[at + 5 + i * 2];
+        const tableByte = tail[at + 6 + i * 2];
+        assignments.push({ id, dc: tableByte >> 4, ac: tableByte & 15 });
+      }
+      scanStart = at + 2 + length;
+      break;
+    }
+    at += 2 + length;
+  }
+  if (scanStart < 0 || assignments.length !== 3)
+    return null;
+  const [lumaH, lumaV] = LUMA_SAMPLING[subsampling] ?? LUMA_SAMPLING[0];
+  const components = [];
+  for (const [index, assignment] of assignments.entries()) {
+    const dc = tables.get(assignment.dc);
+    const ac = tables.get(16 | assignment.ac);
+    if (!dc || !ac)
+      return null;
+    components.push({ h: index === 0 ? lumaH : 1, v: index === 0 ? lumaV : 1, dc, ac, pred: 0 });
+  }
+  const reader2 = new BitReader(tail, scanStart);
+  let luma = new Int32Array(1024);
+  const lumaBlocks = lumaH * lumaV;
+  let mcus = 0;
+  let consumed = reader2.consumed;
+  let complete = false;
+  try {
+    for (; ; ) {
+      if (restartInterval > 0 && mcus > 0 && mcus % restartInterval === 0) {
+        reader2.align();
+        for (const component of components)
+          component.pred = 0;
+      }
+      if (reader2.restarted) {
+        reader2.restarted = false;
+        for (const component of components)
+          component.pred = 0;
+      }
+      let lumaSum = 0;
+      for (const component of components) {
+        for (let block = 0; block < component.h * component.v; block++) {
+          const dc = decodeBlock(reader2, component);
+          if (component === components[0])
+            lumaSum += dc;
+        }
+      }
+      if (mcus === luma.length) {
+        const grown = new Int32Array(luma.length * 2);
+        grown.set(luma);
+        luma = grown;
+      }
+      luma[mcus] = Math.round(lumaSum / lumaBlocks);
+      mcus++;
+      consumed = reader2.consumed;
+      if (consumed >= tail.length) {
+        complete = true;
+        break;
+      }
+    }
+  } catch (error) {
+    if (!(error instanceof ScanEnd))
+      throw error;
+    complete = tail.length - consumed <= 2;
+  }
+  return { mcus, luma: luma.subarray(0, mcus), complete };
+}
+
 // dist/transport/http/decodeImageV2.js
-import { decode as jpegDecode, encode as jpegEncode } from "jpeg-js";
+import { decode as jpegDecode } from "jpeg-js";
 var V2_PREFIX = "v2_eufysecurity:";
 var DC_CHROMA = Buffer.from([255, 196, 0, 31, 1]);
 var ZIGZAG = [
@@ -582,35 +819,6 @@ var DHT_AC_LUMA = Buffer.from("ffc400b5100002010303020403050504040000017d0102030
 var SOI = Buffer.from([255, 216]);
 var APP0 = Buffer.from("ffe000104a46494600010100000100010000", "hex");
 var MCU = { 0: [8, 8], 1: [16, 8], 2: [16, 16] };
-var LADDER = [
-  [160, 90],
-  [240, 135],
-  [256, 144],
-  [320, 180],
-  [384, 216],
-  [400, 225],
-  [480, 270],
-  [512, 288],
-  [576, 324],
-  [640, 360],
-  [704, 396],
-  [768, 432],
-  [848, 480],
-  [960, 540],
-  [1024, 576],
-  [1280, 720],
-  [1600, 900],
-  [1920, 1080],
-  [176, 144],
-  [320, 240],
-  [352, 288],
-  [480, 360],
-  [640, 480],
-  [800, 600],
-  [1024, 768],
-  [256, 480],
-  [320, 384]
-];
 function scaleQuant(base, quality) {
   const factor = quality < 50 ? Math.floor(5e3 / quality) : 200 - quality * 2;
   return base.map((v) => Math.min(255, Math.max(1, Math.floor((v * factor + 50) / 100))));
@@ -647,7 +855,7 @@ function sofSegment(width, height, subsampling) {
     1
   ]);
 }
-function buildHeader(width, height, subsampling, quality = 85) {
+function buildHeader(width, height, subsampling, quality) {
   return Buffer.concat([
     SOI,
     APP0,
@@ -658,99 +866,107 @@ function buildHeader(width, height, subsampling, quality = 85) {
     DHT_AC_LUMA
   ]);
 }
-function decodeCandidate(tail, width, height, subsampling) {
+var PROBE_MEMORY_MB = 24;
+function decodeSpliced(header, tail) {
   try {
-    const jpeg = Buffer.concat([buildHeader(width, height, subsampling), tail]);
-    return jpegDecode(jpeg, { useTArray: true, maxMemoryUsageInMB: 128 });
+    return jpegDecode(Buffer.concat([header, tail]), { useTArray: true, maxMemoryUsageInMB: PROBE_MEMORY_MB });
   } catch {
     return null;
   }
 }
-function colorSpread(img) {
-  const { width, height, data } = img;
-  let sum = 0;
-  let count2 = 0;
-  for (let i = 0; i < width * height; i += 37) {
-    const p = i * 4;
-    const r = data[p];
-    const g = data[p + 1];
-    const b = data[p + 2];
-    sum += Math.abs(r - g) + Math.abs(g - b) + Math.abs(b - r);
-    count2++;
-  }
-  return count2 ? sum / count2 : Number.POSITIVE_INFINITY;
-}
-function rowShear(img, rows) {
-  const { width, data } = img;
-  let sum = 0;
-  let count2 = 0;
-  for (let y = 1; y < rows; y++) {
-    for (let x = 0; x < width; x += 4) {
-      sum += Math.abs(data[(y * width + x) * 4] - data[((y - 1) * width + x) * 4]);
-      count2++;
-    }
+var REFERENCE_QUALITY = 85;
+var MAX_STRETCH = 8;
+var CUTOFF_PERCENT = 0.5;
+function trimmedRange(data, channel, total, cutoff) {
+  const hist = new Array(256).fill(0);
+  for (let i = 0; i < total; i++)
+    hist[data[i * 4 + channel]]++;
+  let remaining = Math.floor(total * cutoff / 100);
+  let lo = 0;
+  while (lo < 255 && remaining > 0) {
+    if (remaining < hist[lo])
+      break;
+    remaining -= hist[lo];
+    lo++;
+  }
+  remaining = Math.floor(total * cutoff / 100);
+  let hi = 255;
+  while (hi > 0 && remaining > 0) {
+    if (remaining < hist[hi])
+      break;
+    remaining -= hist[hi];
+    hi--;
   }
-  return count2 ? sum / count2 : Number.POSITIVE_INFINITY;
+  return { lo, hi };
 }
-function autoContrast(data, width, height, cutoff = 0.5) {
-  const total = width * height;
+function contrastScale(img, cutoff = CUTOFF_PERCENT) {
+  const total = img.width * img.height;
+  if (total === 0)
+    return 1;
+  let stretch = Number.POSITIVE_INFINITY;
   for (let channel = 0; channel < 3; channel++) {
-    const hist = new Array(256).fill(0);
-    for (let i = 0; i < total; i++)
-      hist[data[i * 4 + channel]]++;
-    let remaining = Math.floor(total * cutoff / 100);
-    for (let bin = 0; bin < 256 && remaining > 0; bin++) {
-      if (remaining > hist[bin]) {
-        remaining -= hist[bin];
-        hist[bin] = 0;
-      } else {
-        hist[bin] -= remaining;
-        remaining = 0;
-      }
-    }
-    remaining = Math.floor(total * cutoff / 100);
-    for (let bin = 255; bin >= 0 && remaining > 0; bin--) {
-      if (remaining > hist[bin]) {
-        remaining -= hist[bin];
-        hist[bin] = 0;
-      } else {
-        hist[bin] -= remaining;
-        remaining = 0;
-      }
-    }
-    let lo = 0;
-    while (lo < 256 && hist[lo] === 0)
-      lo++;
-    let hi = 255;
-    while (hi >= 0 && hist[hi] === 0)
-      hi--;
+    const { lo, hi } = trimmedRange(img.data, channel, total, cutoff);
     if (hi <= lo)
       continue;
-    const scale = 255 / (hi - lo);
-    const offset = -lo * scale;
-    const lut = new Uint8Array(256);
-    for (let v = 0; v < 256; v++)
-      lut[v] = Math.min(255, Math.max(0, Math.trunc(v * scale + offset)));
-    for (let i = 0; i < total; i++)
-      data[i * 4 + channel] = lut[data[i * 4 + channel]];
-  }
-}
-function maxHeight(tail, width, subsampling, seed) {
-  const mcuHeight = MCU[subsampling][1];
-  let height = Math.max(mcuHeight, Math.round(seed / mcuHeight) * mcuHeight);
-  if (!decodeCandidate(tail, width, height, subsampling)) {
-    while (height > mcuHeight && !decodeCandidate(tail, width, height, subsampling))
-      height -= mcuHeight;
-  } else {
-    while (height < 4096 && decodeCandidate(tail, width, height + mcuHeight, subsampling))
-      height += mcuHeight;
-  }
-  return height;
-}
-function ladderByMcuCount(subsampling) {
-  const [mcuWidth, mcuHeight] = MCU[subsampling];
-  const mcus = ([width, height]) => width / mcuWidth * (height / mcuHeight);
-  return [...LADDER].sort((a, b) => mcus(a) - mcus(b));
+    if (lo < 128)
+      stretch = Math.min(stretch, 128 / (128 - lo));
+    if (hi > 128)
+      stretch = Math.min(stretch, 127 / (hi - 128));
+  }
+  if (!Number.isFinite(stretch))
+    return 1;
+  return Math.min(MAX_STRETCH, Math.max(1, stretch));
+}
+function qualityForStretch(stretch) {
+  const referenceFactor = REFERENCE_QUALITY < 50 ? Math.floor(5e3 / REFERENCE_QUALITY) : 200 - REFERENCE_QUALITY * 2;
+  const factor = referenceFactor * stretch;
+  const quality = factor <= 100 ? (200 - factor) / 2 : 5e3 / factor;
+  return Math.min(99, Math.max(1, Math.round(quality)));
+}
+var MAX_EDGE = 4096;
+var MIN_ASPECT = 0.4;
+var MAX_ASPECT = 4;
+function mcuRowShear(luma, mcuWidth, mcuHeight) {
+  if (mcuHeight < 2)
+    return Number.POSITIVE_INFINITY;
+  let sum = 0;
+  for (let y = 1; y < mcuHeight; y++) {
+    for (let x = 0; x < mcuWidth; x++)
+      sum += Math.abs(luma[y * mcuWidth + x] - luma[(y - 1) * mcuWidth + x]);
+  }
+  return sum / (mcuWidth * (mcuHeight - 1));
+}
+function bestGeometry(luma, mcus, subsampling) {
+  const [mcuPixelWidth, mcuPixelHeight] = MCU[subsampling];
+  let best = null;
+  for (let mcuWidth = 1; mcuWidth <= mcus; mcuWidth++) {
+    if (mcus % mcuWidth !== 0)
+      continue;
+    const mcuHeight = mcus / mcuWidth;
+    const width = mcuWidth * mcuPixelWidth;
+    const height = mcuHeight * mcuPixelHeight;
+    if (width > MAX_EDGE || height > MAX_EDGE)
+      continue;
+    const aspect = width / height;
+    if (aspect < MIN_ASPECT || aspect > MAX_ASPECT)
+      continue;
+    const shear = mcuRowShear(luma, mcuWidth, mcuHeight);
+    if (!best || shear < best.shear)
+      best = { subsampling, width, height, shear };
+  }
+  return best;
+}
+function findGeometry(tail) {
+  let best = null;
+  for (const subsampling of [0, 1, 2]) {
+    const scan = scanEntropy(tail, subsampling, [DHT_DC_LUMA, DHT_AC_LUMA]);
+    if (!scan?.complete || scan.mcus < 1)
+      continue;
+    const geometry = bestGeometry(scan.luma, scan.mcus, subsampling);
+    if (geometry && (!best || geometry.shear < best.shear))
+      best = geometry;
+  }
+  return best;
 }
 function isV2Image(data) {
   return data.length >= V2_PREFIX.length && data.subarray(0, V2_PREFIX.length).toString("latin1") === V2_PREFIX;
@@ -762,53 +978,17 @@ function decodeImageV2(data) {
   if (cut < 0)
     return null;
   const tail = data.subarray(cut);
-  let best = null;
-  for (const subsampling2 of [2, 0, 1]) {
-    let filled = null;
-    for (const [width2, height2] of ladderByMcuCount(subsampling2)) {
-      const img2 = decodeCandidate(tail, width2, height2, subsampling2);
-      if (!img2)
-        break;
-      if (!filled || width2 * height2 > filled.width * filled.height)
-        filled = { width: width2, height: height2, img: img2 };
-    }
-    if (!filled)
-      continue;
-    const spread = colorSpread(filled.img);
-    if (!best || spread < best.spread)
-      best = { spread, subsampling: subsampling2, width: filled.width, height: filled.height };
-  }
-  if (!best)
+  const geometry = findGeometry(tail);
+  if (!geometry)
     return null;
-  const { subsampling, width: coarseWidth } = best;
-  const [mcuWidth, mcuHeight] = MCU[subsampling];
-  const coarseHeight = maxHeight(tail, coarseWidth, subsampling, best.height);
-  const totalMcus = coarseWidth / mcuWidth * (coarseHeight / mcuHeight);
-  let width = coarseWidth;
-  let height = coarseHeight;
-  let bestShear = Number.POSITIVE_INFINITY;
-  const lowWidth = Math.max(mcuWidth * 4, Math.round(coarseWidth * 0.75 / mcuWidth) * mcuWidth);
-  const highWidth = Math.round(coarseWidth * 1.25 / mcuWidth) * mcuWidth;
-  for (let candidateWidth = lowWidth; candidateWidth <= highWidth; candidateWidth += mcuWidth) {
-    const candidateHeight = Math.floor(totalMcus / (candidateWidth / mcuWidth)) * mcuHeight;
-    if (candidateHeight < mcuHeight)
-      continue;
-    const img2 = decodeCandidate(tail, candidateWidth, candidateHeight, subsampling);
-    if (!img2)
-      continue;
-    const shear = rowShear(img2, candidateHeight);
-    if (shear < bestShear) {
-      bestShear = shear;
-      width = candidateWidth;
-      height = candidateHeight;
-    }
-  }
-  height = maxHeight(tail, width, subsampling, height);
-  const img = decodeCandidate(tail, width, height, subsampling);
-  if (!img)
+  const { width, height, subsampling } = geometry;
+  const reference = buildHeader(width, height, subsampling, REFERENCE_QUALITY);
+  const probe = decodeSpliced(reference, tail);
+  if (!probe)
     return null;
-  autoContrast(img.data, img.width, img.height);
-  return Buffer.from(jpegEncode({ data: img.data, width: img.width, height: img.height }, 90).data);
+  const stretch = contrastScale(probe);
+  const header = stretch > 1.01 ? buildHeader(width, height, subsampling, qualityForStretch(stretch)) : reference;
+  return Buffer.concat([header, tail]);
 }
 
 // dist/transport/http/decodeImageV1.js
@@ -1420,9 +1600,20 @@ var MegaHttpClient = class {
       throw error;
     }
   }
-  /** Download push image bytes and decrypt a recognized v1 wrapper when its device key input is available. */
+  /**
+   * Download push image bytes and decrypt a recognized v1 wrapper when its device key input is available.
+   *
+   * A decoder throw is tagged `decode-failed`: to anything downstream, the difference between "the
+   * bytes never arrived" and "the bytes arrived and the wrapper would not decrypt" is the difference
+   * between a network problem and a key problem, and one of them is this SDK's to fix.
+   */
   async downloadImage(url, p2pDid) {
-    return normalizePushImage(await this.downloadMedia(url), p2pDid);
+    const data = await this.downloadMedia(url);
+    try {
+      return normalizePushImage(data, p2pDid);
+    } catch (error) {
+      throw mediaFailureError("Push image could not be decoded", "decode-failed", error);
+    }
   }
   /** The security-app data host for this region (face recognition, media, etc.). */
   securityAppHost() {
@@ -12880,7 +13071,7 @@ function lz4BlockDecompress(block, size) {
   const end = block.length;
   let pos = 0;
   let written = 0;
-  const extend = (base) => {
+  const extend2 = (base) => {
     let len = base;
     if (base !== 15)
       return len;
@@ -12895,7 +13086,7 @@ function lz4BlockDecompress(block, size) {
   };
   while (pos < end) {
     const token = block[pos++];
-    const literals = extend(token >> 4);
+    const literals = extend2(token >> 4);
     if (literals === void 0)
       return void 0;
     if (pos + literals > end || written + literals > size)
@@ -12910,7 +13101,7 @@ function lz4BlockDecompress(block, size) {
     pos += 2;
     if (offset === 0 || offset > written)
       return void 0;
-    const match = extend(token & 15);
+    const match = extend2(token & 15);
     if (match === void 0)
       return void 0;
     const length = match + 4;
@@ -23367,8 +23558,21 @@ var FileFcmStore = class {
   }
 };
 
+// dist/transport/media-failure.js
+var MEDIA_FAILURE_REASONS = [
+  "url-not-allowed",
+  "address-not-public",
+  "redirect-not-allowed",
+  "http-status",
+  "too-large",
+  "timeout",
+  "network",
+  "decode-failed"
+];
+
 // dist/transport/stored-image-cache.js
 var MAX_JPEG_BYTES = 10 * 1024 * 1024;
+var MAX_REMEMBERED_URLS = 64;
 var DIAGNOSTIC_INTERVAL_MS = 6e4;
 var StoredImageCache = class {
   downloader;
@@ -23385,7 +23589,13 @@ var StoredImageCache = class {
     this.clock = clock;
     this.isLifecycleError = isLifecycleError;
   }
-  /** Observe a normalized thumbnail URL and start acquisition eagerly. */
+  /**
+   * Observe a normalized thumbnail URL and start acquisition eagerly.
+   *
+   * A URL already inside this device's window of recent attempts is ignored, so one event arriving as
+   * several pushes downloads one thumbnail. The window is a `Set`, which iterates in insertion order,
+   * so the entry evicted once it is full is the oldest attempt.
+   */
   observe(deviceKey, url) {
     let state = this.devices.get(deviceKey);
     if (!state) {
@@ -23400,6 +23610,12 @@ var StoredImageCache = class {
     if (state.seenUrls.has(url))
       return;
     state.seenUrls.add(url);
+    while (state.seenUrls.size > MAX_REMEMBERED_URLS) {
+      const oldest = state.seenUrls.values().next();
+      if (oldest.done)
+        break;
+      state.seenUrls.delete(oldest.value);
+    }
     state.queued = {
       deviceKey,
       url,
@@ -23449,7 +23665,7 @@ var StoredImageCache = class {
       } else if (image === void 0) {
         state.lifecycleError = void 0;
         state.reason = "download-failed";
-        this.diagnose(state, candidate, "download-failed");
+        this.diagnose(state, candidate, "download-failed", error);
       } else if (!this.isValidJpeg(image)) {
         state.lifecycleError = void 0;
         state.reason = "invalid-image";
@@ -23465,7 +23681,7 @@ var StoredImageCache = class {
   isValidJpeg(image) {
     return Buffer.isBuffer(image) && image.length > 0 && image.length <= MAX_JPEG_BYTES && image.length >= 5 && image[0] === 255 && image[1] === 216 && image[2] === 255 && image[image.length - 2] === 255 && image[image.length - 1] === 217;
   }
-  diagnose(state, candidate, failure) {
+  diagnose(state, candidate, failure, error) {
     const now2 = this.clock();
     const last = state.loggedFailures.get(failure);
     if (last !== void 0 && now2 - last < DIAGNOSTIC_INTERVAL_MS)
@@ -23473,11 +23689,23 @@ var StoredImageCache = class {
     state.loggedFailures.set(failure, now2);
     this.logger.warn("[stored-snapshot-cache] candidate failed", {
       class: failure,
+      ...mediaFailureTag(error),
       observedAt: candidate.observedAt,
       retained: state.retained !== void 0
     });
   }
 };
+function mediaFailureTag(error) {
+  if (typeof error !== "object" || error === null)
+    return {};
+  const { mediaFailure, status } = error;
+  if (typeof mediaFailure !== "string")
+    return {};
+  const cause = MEDIA_FAILURE_REASONS.find((reason) => reason === mediaFailure);
+  if (!cause)
+    return {};
+  return Number.isInteger(status) && status >= 100 && status <= 599 ? { cause, status } : { cause };
+}
 
 // dist/client/device-registry.js
 function resolvedStationSn(raw, sn) {
@@ -26747,7 +26975,6 @@ export {
   aesKey,
   asBool,
   assertNever,
-  autoContrast,
   bizChannelName,
   buildActions,
   buildAppShapedClientId,