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

package/dist/transport/http/decodeImageV2.d.ts

@@ -1,19 +1,13 @@
-/**
- * Per-channel auto-contrast, a byte-exact port of PIL `ImageOps.autocontrast` (cutoff 0.5%). The lost
- * quant tables leave the reconstruction low-contrast ("foggy"); stretching each channel's clipped range
- * to full scale restores a natural-looking image. Mutates `data` (RGBA) in place.
- *
- * Parity notes vs PIL: the cutoff count is `n * cutoff // 100` (integer floor); it is trimmed off each
- * end by zeroing whole histogram bins until the count is spent; the range is then the first/last
- * non-empty bins; and the LUT truncates toward zero (`int()`), NOT rounds — rounding would shift pixels.
- */
-export declare function autoContrast(data: Uint8Array, width: number, height: number, cutoff?: number): void;
 /** True if the blob is a v2 `v2_eufysecurity:` push thumbnail. */
 export declare function isV2Image(data: Buffer): boolean;
 /**
- * Decode a v2 blob to a plain JPEG buffer by reconstructing its header, or null if it isn't v2 or the
- * plaintext scan can't be located. The search first chooses subsampling and coarse geometry, derives
- * the fixed MCU count, refines width by row shear, and pins the exact fill height before applying
- * auto-contrast and re-encoding. See the module doc for the keyless-splice rationale.
+ * Decode a v2 blob to a plain JPEG buffer by reconstructing its header, or null if it isn't v2, the
+ * plaintext scan can't be located, or no frame shape explains it.
+ *
+ * Three steps and no pixel rewrite: the frame shape is read out of the entropy scan,
+ * one probe decode both proves the spliced JPEG decodes and measures how far the substitute quant
+ * tables fall short of the camera's, and the answer is the same tail under a header carrying the
+ * corrected tables. See the module doc for the keyless-splice rationale and for why neither the search
+ * nor the correction decodes candidate frames or re-encodes the picture.
  */
 export declare function decodeImageV2(data: Buffer): Buffer | null;

package/dist/transport/http/jpeg-scan.d.ts

@@ -0,0 +1,59 @@
+/**
+ * A baseline-JPEG entropy scanner that decodes no pixels.
+ *
+ * The v2 thumbnail decoder next door has to discover a frame geometry its blob does not state, and the
+ * only evidence is the plaintext entropy-coded scan: how many MCUs it carries, and whether it carries
+ * them under a given chroma subsampling. A JPEG decoder answers that — it throws on a frame the scan
+ * does not fill — and charges a full set of component and output buffers for each question.
+ *
+ * That bill is fatal for a caller under a hard memory cap. Each `jpeg-js` decode churns roughly a
+ * megabyte of typed arrays, glibc keeps the arenas rather than handing them back, and a search asking
+ * the question of every candidate geometry costs tens of megabytes per thumbnail — permanently, and
+ * more than an embedded host gives an app in total.
+ *
+ * This module asks the same question by walking the Huffman-coded coefficients and throwing them away:
+ * no IDCT, no component planes, no output image. What it keeps is one number per MCU — the DC
+ * coefficient of its luma block(s), i.e. that block's average brightness — which is all the geometry
+ * search needs to tell a sheared row apart from a continuous one. Allocation is a single `Int32Array`
+ * of MCU count, and the walk is linear in the scan's length.
+ *
+ * Baseline sequential only (SOF0), which is what the v2 tail is: no progressive refinement, no
+ * arithmetic coding. Restart markers are tolerated — the scan resynchronises and resets its DC
+ * predictors, exactly as a decoder would.
+ *
+ * @module transport/http/jpeg-scan
+ */
+/** What the scan carried, under one subsampling hypothesis. */
+export interface EntropyScan {
+    /** Complete MCUs decoded before the data ran out. */
+    mcus: number;
+    /**
+     * Mean luma DC per MCU, in scan order — a thumbnail of the picture at MCU resolution.
+     *
+     * Quantized units (the quant tables are lost with the v2 head), so the values are a scale of their
+     * own. Differences between neighbours are what the geometry search reads, and those survive.
+     */
+    luma: Int32Array;
+    /**
+     * Whether the scan ended where a whole MCU ended, with nothing but the EOI marker left.
+     *
+     * The discriminator between hypotheses: a wrong one reads a block with the wrong Huffman table,
+     * diverges, and either dies mid-MCU or stops with data still ahead of it. Only the subsampling the
+     * encoder used walks the scan to its last byte on an MCU boundary.
+     */
+    complete: boolean;
+}
+/**
+ * Walk the plaintext tail's scan under one subsampling hypothesis.
+ *
+ * `extraTables` carries the DHT segments that are NOT in the tail — for a v2 thumbnail, the standard
+ * luma tables the reconstructed header supplies, since only the chroma ones survive in plaintext.
+ * Returns null when the tail is not a baseline scan at all (no SOS, missing tables).
+ *
+ * The walk stops at the first byte it cannot read as this hypothesis's next block, and the result is
+ * `complete` only when that happened on an MCU boundary with nothing but a marker left. The DC array
+ * grows as the scan turns out to be long rather than being sized from the scan's byte length: a wrong
+ * hypothesis dies after a handful of MCUs, and provisioning three whole-scan arrays to discover that is
+ * the kind of allocation this module exists to avoid.
+ */
+export declare function scanEntropy(tail: Uint8Array, subsampling: number, extraTables: readonly Uint8Array[]): EntropyScan | null;

package/dist/transport/http/media-download.d.ts

@@ -1,7 +1,10 @@
+import type { MediaFailureReason } from "../media-failure.js";
 type ResolveHost = (hostname: string) => Promise<readonly {
     address: string;
     family: number;
 }[]>;
+/** Tag a failure OUTSIDE the transfer itself — the push-image decoder refusing bytes that did arrive. @internal */
+export declare function mediaFailureError(message: string, reason: MediaFailureReason, cause?: unknown): Error;
 /** Signals rejection of the active Eufy session without exposing response content. @internal */
 export declare class MediaDownloadAuthenticationError extends Error {
 }

package/dist/transport/http/mega-client.d.ts

@@ -353,7 +353,13 @@ export declare class MegaHttpClient {
     registerPushToken(token: string): Promise<void>;
     /** Download raw bytes from a push-media URL using the active account session. */
     downloadMedia(url: string): Promise<Buffer>;
-    /** 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.
+     */
     downloadImage(url: string, p2pDid?: string): Promise<Buffer>;
     /** The security-app data host for this region (face recognition, media, etc.). */
     private securityAppHost;

package/dist/transport/media-failure.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Why acquiring a push thumbnail produced no bytes.
+ *
+ * Transport vocabulary, and it stays inside `transport/`: the modules that raise it and the cache that
+ * reads it are both here, and neither the device model nor the client names it. Nothing crosses the
+ * capability boundary, so nothing belongs in the shared floor.
+ *
+ * @module transport/media-failure
+ */
+/**
+ * The terms an acquisition failure is reported in — a CLOSED vocabulary, and that is the point.
+ *
+ * `download-failed` says a candidate did not become an image; it does not say whether the URL was
+ * refused before a packet moved, the host answered 404, the transfer timed out, or the bytes arrived
+ * and would not decode. Those need entirely different fixes, so the distinction has to survive to
+ * whatever is reading the log.
+ *
+ * It is a fixed vocabulary rather than an error message because the thing that fails holds a signed
+ * media URL and a response body, and neither may reach a log line. Every member here is a term this
+ * file defines; a downloader's own wording never is.
+ *
+ * - `url-not-allowed` — the candidate URL failed the media allowlist (scheme, credentials, port, a
+ *   literal address, or a host the SDK does not download from). Nothing was requested.
+ * - `address-not-public` — the host resolved to nothing, or to an address that is not public.
+ * - `redirect-not-allowed` — the media host redirected somewhere the object-store allowlist refuses,
+ *   redirected without a target, or redirected twice.
+ * - `http-status` — the host answered, with a status other than 200. Carried alongside as `status`.
+ * - `too-large` — the body exceeded the download bound, declared or observed.
+ * - `timeout` — the whole attempt, DNS included, outlived its window.
+ * - `network` — the request itself failed: connect, TLS, a reset mid-body.
+ * - `decode-failed` — the bytes arrived and the push-image decoder refused them. A property of the
+ *   image, not of the network.
+ */
+export type MediaFailureReason = "url-not-allowed" | "address-not-public" | "redirect-not-allowed" | "http-status" | "too-large" | "timeout" | "network" | "decode-failed";
+/** Every {@link MediaFailureReason}, so a tag that crossed an injected boundary can be checked against it. */
+export declare const MEDIA_FAILURE_REASONS: readonly MediaFailureReason[];
+/**
+ * The tag a media-acquisition failure carries for diagnostics.
+ *
+ * A property rather than a base class: the cache that logs it takes its downloader by injection and
+ * must not import the transport that throws — so it reads this shape off an unknown error and checks
+ * the term against {@link MEDIA_FAILURE_REASONS} before it goes anywhere near a log.
+ */
+export interface MediaFailure {
+    readonly mediaFailure: MediaFailureReason;
+    /** The HTTP status, when {@link mediaFailure} is `http-status`. */
+    readonly status?: number;
+}

package/dist/transport/stored-image-cache.d.ts

@@ -10,7 +10,13 @@ export declare class StoredImageCache {
     private activeDownloads;
     private generation;
     constructor(downloader: (url: string, deviceKey: string) => Promise<Buffer>, logger: Logger, clock?: () => number, isLifecycleError?: (error: unknown) => boolean);
-    /** 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: string, url: string): void;
     /** Return retained bytes without starting or awaiting network work. */
     snapshotStored(deviceKey: string): Promise<Buffer>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mega-yfue/eufy-sdk",
-  "version": "0.2.0-beta.14",
+  "version": "0.2.0-beta.15",
   "description": "One typed TypeScript client for the Anker eufy v6 cloud — capability-driven devices, realtime events over P2P/MQTT/push, and live media",
   "license": "Apache-2.0",
   "author": "mega-yfue",