@mega-yfue/eufy-sdk 0.2.0-beta.13 → 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/p2p/command-router.d.ts

@@ -28,10 +28,12 @@ import { FragmentRecording } from "./fragment-recording.js";
  * when these change.
  *
  * `connect` applies to every call on a station, because nothing can be addressed to one before its session is
- * up. `level2Grace` applies twice where the key is required: the negotiation is re-prompted once.
+ * up, and it is the session's own connect deadline: a session that reaches it closes itself, so waiting past it
+ * waits on a connection that can no longer answer. `level2Grace` applies twice where the key is required: the
+ * negotiation is re-prompted once.
  */
 export declare const P2P_STATION_WAITS: {
-    readonly connect: 20000;
+    readonly connect: 15000;
     readonly level2Grace: 25000;
     readonly level2Settle: 8000;
 };

package/dist/transport/p2p/live-trace.d.ts

@@ -63,6 +63,20 @@ export type LiveTrace =
     phase: "sequence-restart";
     dataType: number;
 }
+/**
+ * Which lookup channels a connection can ask for the station on, before it asks.
+ *
+ * A station is found by a local lookup, by a cloud lookup, or by both, and each needs something the other
+ * does not: the local one needs the station on this link, the cloud one needs both a key for the station and
+ * an address to ask. A connect that had one channel failed for that channel's reason alone, and a connect
+ * that had neither could not have succeeded — outcomes a station that is switched off is otherwise
+ * indistinguishable from, because nothing else in a failed connect states what was even attempted.
+ */
+ | {
+    phase: "lookup-channels";
+    local: boolean;
+    cloud: boolean;
+}
 /**
  * Work on a station is holding for its session to connect, with the milliseconds it will wait.
  *
@@ -150,17 +164,21 @@ export type LiveTrace =
 /**
  * A station was resolved for a call, stating what the caller's device is on it and whose station it is.
  *
- * Emitted before anything is sent, so it is the only account of the intended topology on a call that fails
- * during resolution: an attached camera's media start has no unencrypted form, so whether a device was taken
- * as attached decides what its failure means. `stationAdmin` states whether the signed-in account is the
- * station's administrator, which is what a key the account cannot resolve turns on; `unstated` is a device
- * record that names no administrator, which is not the same as naming another.
+ * Emitted before the session is waited on, so a station that is never reached still has this record: an
+ * attached camera's media start has no unencrypted form, so whether a device was taken as attached decides
+ * what its failure means. `stationAdmin` states whether the signed-in account is the station's
+ * administrator, which is what a key the account cannot resolve turns on; `unstated` is a device record
+ * that names no administrator, which is not the same as naming another. `stationModel` is the model of the
+ * station the call resolved — the base's for an attached camera, the device's own where it is its own
+ * station — absent where that record states none; without it a base this SDK reaches differently is
+ * indistinguishable from one that is switched off.
  */
  | {
     phase: "station-resolved";
     topology: "attached" | "own";
     channel: number;
     stationAdmin: "self" | "other" | "unstated";
+    stationModel?: string;
 }
 /** A shared source began warming, with the interval it re-issues on and the deadline it fails at. */
  | {

package/dist/transport/p2p/p2p-session.d.ts

@@ -16,6 +16,15 @@
 import { EventEmitter } from "node:events";
 import { type Address, type P2PDataFrameHeader } from "./codec.js";
 import { type Logger } from "../../core/logger.js";
+/**
+ * How long a station is given to answer a lookup before the connection gives up on it and closes.
+ *
+ * The whole deadline for reaching a station: the lookups are re-sent every second until one is answered, and
+ * a connection that reaches this closes itself, so nothing addressed to that station can succeed afterwards.
+ * Published because it bounds every wait on a session connecting — a second number for the same deadline
+ * elsewhere would outlive the connection it waits on and charge the difference to every failure.
+ */
+export declare const CONNECT_TIMEOUT_MS = 15000;
 /**
  * The channel a command addresses the station itself on, rather than one of its cameras, and the value a
  * session's channel-taking methods resolve an omitted channel to.

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.13",
+  "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",