@mega-yfue/eufy-sdk 0.0.4 → 0.1.0-beta.0

package/dist/transport/push/types.d.ts

@@ -0,0 +1,180 @@
+/**
+ * eufy FCM push payload types.
+ *
+ * A push arrives as an MCS DataMessageStanza whose `app_data` has a `payload`
+ * entry = base64( NUL-terminated JSON ). That JSON is the EufyPushMessage; its
+ * nested `payload` is device-type specific. The v6 app enriches these with AI
+ * detection fields (person/vehicle/pet/package/faces/crops/short video) — see
+ * PushEnrichment.
+ */
+/**
+ * Raw MCS frame: a tag + the decoded protobuf object.
+ *
+ * A framed message off the push socket — internal wire shape.
+ * @internal
+ */
+export interface McsMessage {
+    tag: number;
+    object: any;
+}
+/**
+ * Outer FCM message after app_data extraction.
+ *
+ * The undecoded push envelope, surfaced on the facade's diagnostic event only.
+ * @internal
+ */
+export interface RawPushMessage {
+    id?: string;
+    from?: string;
+    to?: string;
+    category?: string;
+    persistentId?: string;
+    ttl?: number;
+    sent?: string;
+    /** The decoded eufy payload (the `payload` app_data entry, JSON-parsed). */
+    payload: EufyPushMessage;
+}
+/** The eufy JSON envelope inside the push. */
+export interface EufyPushMessage {
+    type?: string | number;
+    title?: string;
+    content?: string;
+    device_sn?: string;
+    station_sn?: string;
+    event_time?: string;
+    push_time?: string;
+    doorbell?: string;
+    "google.c.sender.id"?: string;
+    /** Device-type specific body (often a JSON string that we further parse). */
+    payload?: PushPayload;
+    [k: string]: unknown;
+}
+/** v6 AI/media enrichment fields (optional; present on newer cameras/doorbells). */
+export interface PushEnrichment {
+    /** Comma list of detection types, e.g. "0,1,2,3" (person/vehicle/pet/package). */
+    ai_detect_type?: string;
+    /** Detected object class names. */
+    objects?: string[] | {
+        names?: string[];
+    };
+    person?: string | number;
+    person_id?: number;
+    person_count?: number;
+    ai_faces?: Array<{
+        face_id?: number;
+        confidence?: number;
+        x?: number;
+        y?: number;
+        width?: number;
+        height?: number;
+    }>;
+    face_id?: number;
+    face_ids?: number[];
+    familiar_faces?: unknown[];
+    vehicle_types?: string[];
+    pet_type?: string | number;
+    /** Sound/cry detection (indoor). */
+    crying?: number | boolean;
+    sound_detection?: number | boolean;
+    sound_type?: string | number;
+    /** Media enrichment. */
+    thumbnail?: string;
+    short_video_url?: string;
+    video_url?: string;
+    cover_path?: string;
+    crop_local_path?: string;
+    crop_url?: string;
+    /** Timing. */
+    trigger_time?: number;
+    duration?: number;
+    event_end_time?: number;
+}
+/**
+ * Normalised device push payload. Superset of the common fields across device
+ * types plus the v6 enrichment; concrete pushes populate a subset. The short
+ * single-letter keys are eufy's wire names (kept for fidelity).
+ */
+export interface PushPayload extends PushEnrichment {
+    device_sn?: string;
+    station_sn?: string;
+    s?: string;
+    name?: string;
+    device_name?: string;
+    nick_name?: string;
+    n?: string;
+    channel?: number;
+    c?: number;
+    a?: number;
+    event_type?: number;
+    msg_type?: number;
+    type?: number;
+    alarm_type?: number;
+    mode?: number;
+    arming?: number;
+    notification_style?: number;
+    e?: string;
+    /** Unverified vendor field; polarity and entity scope are not established. */
+    m?: number;
+    pic_url?: string;
+    file_path?: string;
+    p?: string;
+    storage_type?: number;
+    cipher?: number;
+    k?: number;
+    create_time?: number;
+    event_time?: number;
+    trigger_time?: number;
+    session_id?: string;
+    unique_id?: string;
+    push_count?: number;
+    user_id?: string;
+    user_name?: string;
+    short_user_id?: string;
+    [k: string]: unknown;
+}
+/** Facts available to attribute a push-provided thumbnail candidate. */
+export type ThumbnailCandidateAttribution = {
+    kind: "device";
+    deviceSn: string;
+} | {
+    kind: "station";
+    stationSn?: string;
+} | {
+    kind: "ambiguous";
+};
+/** A push-provided thumbnail URL together with its transport-level attribution facts. */
+export interface ThumbnailCandidate {
+    url: string;
+    attribution: ThumbnailCandidateAttribution;
+}
+/** A normalised, consumer-facing push event emitted by the client. */
+export interface PushEvent {
+    /** Best-effort device serial (falls back to station). */
+    deviceSn?: string;
+    stationSn?: string;
+    /** Numeric event type as the cloud sends it; `eventName` carries the resolved label. */
+    eventType?: number;
+    /** Resolved event name where known. */
+    eventName?: string;
+    /** The thumbnail URL, if the push carried one (pic_url/thumbnail). */
+    thumbnailUrl?: string;
+    /** A usable thumbnail URL and the identity claims carried beside it. */
+    thumbnailCandidate?: ThumbnailCandidate;
+    /** Cipher id for decoding the media (when present). */
+    cipher?: number;
+    /** The full parsed eufy payload. */
+    payload: PushPayload;
+    /** The whole raw push (envelope + app_data). */
+    raw: RawPushMessage;
+}
+/** Persisted FCM credentials so we register once and reconnect across runs. */
+export interface FcmCredentials {
+    fid: string;
+    androidId: string;
+    securityToken: string;
+    /** The FCM registration token (what we hand to eufy's cloud). */
+    fcmToken: string;
+    /** Firebase installation refresh token (for auth-token renewal). */
+    refreshToken?: string;
+    createdAt: number;
+}

package/dist/transport/raw-dp.d.ts

@@ -0,0 +1,6 @@
+import type { RawDpCodec } from "../core/contracts.js";
+/**
+ * The codec every Raw-DP reader shares. Stateless, so one frozen instance serves every device — there
+ * is nothing per-device or per-DP to configure.
+ */
+export declare const rawDpCodec: RawDpCodec;

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

@@ -0,0 +1,23 @@
+import type { Logger } from "../core/logger.js";
+/** In-memory state for push thumbnails acquired before a caller passively reads them. */
+export declare class StoredImageCache {
+    private readonly downloader;
+    private readonly logger;
+    private readonly clock;
+    private readonly isLifecycleError;
+    private readonly devices;
+    private readonly activeDevices;
+    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(deviceKey: string, url: string): void;
+    /** Return retained bytes without starting or awaiting network work. */
+    snapshotStored(deviceKey: string): Promise<Buffer>;
+    /** Invalidate all retained and candidate state. */
+    clear(): void;
+    private pump;
+    private complete;
+    private isValidJpeg;
+    private diagnose;
+}

package/dist/transport/tuya/account.d.ts

@@ -0,0 +1,44 @@
+/** Username/plaintext prefix the app prepends to the eufy user id. */
+export declare const TUYA_USERNAME_PREFIX = "eufyhome-";
+/** AES-128-CBC key used to derive the Tuya password (16 bytes). */
+export declare const TUYA_PASSWORD_KEY: Buffer<ArrayBuffer>;
+/** AES-128-CBC IV used to derive the Tuya password (16 bytes). */
+export declare const TUYA_PASSWORD_IV: Buffer<ArrayBuffer>;
+/** The Tuya username for a eufy user id (`"eufyhome-" + eufyUserId`). */
+export declare function tuyaUsername(eufyUserId: string): string;
+/**
+ * Derive the Tuya password for a eufy user id:
+ * `UPPERCASE-HEX( AES-128-CBC-NoPadding( pad16("eufyhome-"+eufyUserId), KEY, IV ) )`.
+ * Deterministic (fixed KEY/IV) — the same user id always yields the same password.
+ */
+export declare function deriveTuyaPassword(eufyUserId: string): string;
+/**
+ * Map an ISO 3166-1 alpha-2 country code (e.g. `"GB"`, `"DE"`) to its E.164 numeric dial code.
+ * Covers the main eufy device markets. Returns `undefined` for unlisted codes — callers fall back
+ * to the region-based heuristic.
+ */
+export declare function isoToDialCode(iso: string): string | undefined;
+/**
+ * Resolve the Tuya `countryCode` login field. Priority:
+ *  1. `phoneCode` — an explicit numeric dial code (e.g. `"49"`) when the caller already has one.
+ *  2. `isoCode` — an ISO 3166-1 alpha-2 code (e.g. `"DE"` from `MegaClientConfig.countryCode`) looked up
+ *     via {@link isoToDialCode}. Covers the full eufy market range, so a German user on the EU
+ *     shard correctly receives `"49"` rather than the coarse region fallback's `"44"`.
+ *  3. `region` — coarse mega shard prefix fallback: `"EU"`→`"44"`, `"CN"`→`"86"`, else `"1"`.
+ */
+export declare function resolveCountryCode(phoneCode?: string, region?: string, isoCode?: string): string;
+/** A derived Tuya login identity — everything needed to call the uid token/password login actions. */
+export interface TuyaAccount {
+    /** `"eufyhome-" + eufyUserId`. */
+    username: string;
+    /** AES-derived password (uppercase hex). See {@link deriveTuyaPassword}. */
+    password: string;
+    /** Tuya `countryCode` field. See {@link resolveCountryCode}. */
+    countryCode: string;
+}
+/**
+ * Derive the full {@link TuyaAccount} (username + password + countryCode) for a eufy user id.
+ * `phoneCode` is the eufy account's phone country code; when omitted the countryCode defaults to
+ * "1" (see {@link resolveCountryCode} for the region-based fallback).
+ */
+export declare function deriveTuyaAccount(eufyUserId: string, phoneCode?: string): TuyaAccount;

package/dist/transport/tuya/client.d.ts

@@ -0,0 +1,89 @@
+import { type TuyaSigner } from "./sign.js";
+import { type TuyaAction, type TuyaEnv, type TuyaEnvelope, type TuyaSession, type TuyaHttpPost } from "./request.js";
+/** Result of a successful {@link TuyaClient.login}. */
+export interface TuyaLoginResult {
+    sid: string;
+    /** Tuya user id (`uid`) from the login response. */
+    uid: string;
+}
+export interface TuyaClientConfig {
+    /**
+     * The native sign seam. Defaults to {@link HmacSigner} with the built-in app key — no config
+     * needed. Override only for tests (pass a {@link StubSigner} or custom impl).
+     */
+    signer?: TuyaSigner;
+    /**
+     * Channel key — defaults to {@link TUYA_CHKEY} (`"7cbfe6d8"`), the constant extracted from
+     * the eufy Security/Mega app. Override only for non-standard builds.
+     */
+    chKey?: string;
+    /** Per-install device id; a random 44-hex one is generated if omitted (see {@link genDeviceId}). */
+    deviceId?: string;
+    /** Restore a prior session id (skip login). */
+    sid?: string;
+    /** Override the environment/static fields (see {@link TuyaEnv}). */
+    env?: TuyaEnv;
+    /** api.json endpoint override (region shard). */
+    endpoint?: string;
+    /** Inject a POST transport (test stub); default = native fetch. */
+    http?: TuyaHttpPost;
+}
+/**
+ * Generate a per-install `deviceId` (44 hex chars). The app derives it deterministically per
+ * install from device fingerprints, but the scheme is not reversed — we mint a random id instead.
+ * TODO(scheme): replace with the app's real derivation once known.
+ */
+export declare function genDeviceId(): string;
+export declare class TuyaClient {
+    private readonly signer;
+    private readonly env;
+    private readonly endpoint?;
+    private readonly http?;
+    private session;
+    constructor(config?: TuyaClientConfig);
+    /** The current per-install session identity (sid empty until {@link login}). */
+    getSession(): Readonly<TuyaSession>;
+    /** True once a login has populated a session id. */
+    get loggedIn(): boolean;
+    /**
+     * Build the full signed param map for an action against the current session. Does not send.
+     * Requires a working signer (the sign step).
+     */
+    buildRequest(action: TuyaAction): Record<string, string>;
+    /** Build + POST an action, returning the parsed envelope. Requires a working signer. */
+    call<T = unknown>(action: TuyaAction): Promise<TuyaEnvelope<T>>;
+    /**
+     * Log into the Tuya cloud from a eufy user id (wire-confirmed from the eufy Security app).
+     *
+     * Flow:
+     *  1. `smartlife.m.user.username.token.get` → `{ token, publicKey, exponent }` (RSA-2048 key).
+     *     If this returns USER_NOT_EXIST the shadow account has never been provisioned — the vacuum
+     *     must be added via the eufy Security app (`com.oceanwing.battery.cam`) at least once.
+     *  2. Derive password: RSA/PKCS1-encrypt( MD5hex(aesPassword), serverKey ) → hex.
+     *  3. `smartlife.m.user.uid.password.login.reg` → `{ sid, uid }`.
+     *     On USER_PASSWD_WRONG: re-fetch a token and retry once with the hardcoded fallback
+     *     password `"12345678"` (wire-confirmed from the eufy Security app).
+     *     ⚠️ Two failed attempts in a row can contribute to Tuya-side rate-limiting or lockout — do not
+     *     add further retry loops on top of this one.
+     */
+    login(eufyUserId: string, phoneCode?: string): Promise<TuyaLoginResult>;
+    /**
+     * READ/dump a device's cached data-points (`thing.m.device.cache.dp.get`).
+     * Builds the request without needing a working signer; the signer is only exercised on send.
+     */
+    getDeviceDps<T = unknown>(devId: string, dpCacheType?: number): Promise<TuyaEnvelope<T>>;
+    /**
+     * CONTROL: publish data-points to a device (`thing.m.device.dp.publish`). `dps` is
+     * `{ "<dpId>": <value> }`. `gwId` is the gateway/parent id (equals `devId` for a standalone gw).
+     *
+     * ⚠️ UNVERIFIED write — refuses to send by default. The `dp.publish` param shape
+     * ({@link buildPublishDpsAction}) is derived, NOT pinned against a confirmed exchange,
+     * and the login round-trip that yields a real `sid` is unproven too. A wrong shape comes back as a
+     * generic Tuya error indistinguishable from a real device rejection, so blindly sending would hide
+     * that ambiguity. Pass `{ allowUnverified: true }` to send anyway; the gate drops when the write is
+     * captured + confirmed against a device.
+     */
+    publishDps<T = unknown>(devId: string, gwId: string, dps: Record<string, unknown>, opts?: {
+        allowUnverified?: boolean;
+    }): Promise<TuyaEnvelope<T>>;
+}

package/dist/transport/tuya/command-router.d.ts

@@ -0,0 +1,79 @@
+/**
+ * `TuyaCommandRouter` — the transport-side command router for eufy Home/Clean Tuya vacuums (X8,
+ * G-series and other `eufy_home_tuya` category devices).
+ *
+ * Usage: call {@link bind} after a successful mega login, then {@link registerDevice} for each
+ * `eufy_home_tuya` device (the facade does both). On the first {@link dispatchCommand} the router
+ * logs into the Tuya cloud lazily (once, shared across all subsequent sends). The dp.publish write
+ * is sent via `TuyaClient.publishDps` — note the `dp.publish` param shape is not yet confirmed from
+ * a live eufy Home/Clean capture (gated by {@link TuyaCommandRouterConfig.allowUnverified}, default `false`).
+ *
+ * Layering: imports `../../core` only — no `model/` import, consistent with the capability↔transport
+ * decorrelation invariant. Sibling tuya/* imports are same-layer (transport).
+ */
+import type { Command } from "../../core/contracts.js";
+import type { TuyaHttpPost } from "./request.js";
+export interface TuyaCommandRouterConfig {
+    /**
+     * Opt-in to unverified Tuya DP writes. Defaults to `false` — {@link dispatchCommand} will throw
+     * until a live `publishDps` capture confirms the dp.publish round-trip. Set `true` only after that
+     * confirmation and remove the gate when the write is shipped as verified.
+     */
+    allowUnverified?: boolean;
+    /** Inject a POST transport (test stub); default = native fetch. Forwarded to the internal TuyaClient. */
+    http?: TuyaHttpPost;
+}
+export declare class TuyaCommandRouter {
+    private readonly allowUnverified;
+    private readonly http;
+    private userId;
+    private dialCode;
+    private client;
+    /** Promise that resolves once Tuya login has completed. Reset by {@link bind}. */
+    private loginOnce;
+    /**
+     * eufy SN → Tuya device ids, populated by the facade via {@link registerDevice}.
+     * The facade extracts the Tuya id from the `raw` device record fields (`tuya_uuid`,
+     * `tuya_virtual_id`, `tuya_device_id`, `virtualId`) and registers it once the device list loads.
+     */
+    private readonly snMap;
+    constructor(config?: TuyaCommandRouterConfig);
+    /**
+     * Supply credentials for lazy Tuya login. Called by the facade after a successful mega login.
+     * The router logs into Tuya on the first {@link dispatchCommand}, not immediately.
+     *
+     * `regionShard` is the mega shard string (`"eu-pr"`, `"us-pr"`, …) used as a coarse fallback;
+     * `isoCode` is the ISO 3166-1 alpha-2 country code from {@link MegaClientConfig} (e.g. `"DE"`)
+     * and takes precedence — a German user on the EU shard gets dial code `"49"`, not `"44"`.
+     */
+    bind(userId: string, regionShard?: string, isoCode?: string): void;
+    /**
+     * Register a eufy SN → Tuya devId mapping. Called by the facade for each `eufy_home_tuya`
+     * device after the cloud device list loads. The facade extracts the Tuya id from the device's
+     * raw record (`tuya_uuid` / `tuya_virtual_id` / `tuya_device_id` / `virtualId` fields).
+     * `gwId` defaults to `devId` — standalone devices share the two.
+     */
+    registerDevice(sn: string, devId: string, gwId?: string): void;
+    private ensureLoggedIn;
+    /**
+     * Fetch a device's cached DPs from the Tuya cloud (`thing.m.device.cache.dp.get`) and deliver
+     * the raw DP map to the caller. Used for initial state hydration after MQTT subscribe — gets the
+     * last-known state without waiting for the first realtime push.
+     *
+     * The response shape from `getDeviceDps` is not yet pinned from a live capture. The defensive
+     * extraction tries both `result.dps` (a nested map) and bare `result` (a flat map), and returns
+     * `null` when neither yields a non-empty record.
+     */
+    fetchDps(sn: string): Promise<Record<string, unknown> | null>;
+    /**
+     * Route an `aiot-dp` {@link Command} to the Tuya REST API.
+     *
+     * Logs in lazily on first call. The eufy SN must have been registered via {@link registerDevice}
+     * before dispatch — the facade does this when the device list is loaded.
+     *
+     * ⚠️ `dp.publish` is unverified — see {@link TuyaCommandRouterConfig.allowUnverified}. By default
+     * this throws. Pass `allowUnverified: true` in the router config only after a live capture
+     * confirms the full round-trip, then remove the gate.
+     */
+    dispatchCommand(sn: string, cmd: Command): Promise<void>;
+}

package/dist/transport/tuya/dp-codec.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Inbound Tuya DP event parsing and routing for eufy Home/Clean (`eufy_home_tuya`) devices.
+ *
+ * {@link parseTuyaDpReport} unwraps the Anker MQTT `{head, payload}` envelope and extracts the
+ * raw DP map. {@link parseTuyaDpEvent} then validates and normalises it to a numeric-keyed record.
+ * {@link TuyaDpRouter} delivers the result to the registered {@link TuyaDpInbound} listener so the
+ * capability layer can consume Tuya state through the same typed getters as AIoT.
+ *
+ * Inbound messages arrive on `cmd/eufy_home/{model}/{sn}/res` with `sign_code: 0` (no additional
+ * encryption — confirmed from clean-device captures). If a future capture shows `sign_code ≠ 0` the
+ * payload will be AES-128-ECB encrypted with the device's localKey before the JSON can be parsed.
+ */
+import type { TuyaDpInbound } from "../../core/contracts.js";
+/**
+ * Validate and convert a raw ThingClips DP callback payload to a numeric-keyed record.
+ *
+ * The callback delivers `{ "<dpId>": <value>, … }` with string keys and typed values; this
+ * normalises the keys to positive integer DP ids. Unrecognised keys (non-positive-integer, non-scalar
+ * values) are skipped rather than rejecting the whole map — the same defensive posture as
+ * {@link parseAiotDpReport}. Returns `null` only when the input is not a non-empty object or when no
+ * valid DP entry was found.
+ */
+export declare function parseTuyaDpEvent(payload: unknown): Record<number, boolean | number | string> | null;
+/**
+ * Extract a raw DP map from an inbound Anker MQTT message for a `eufy_home_tuya` device.
+ *
+ * Messages arrive in the same `{head, payload}` envelope the AIoT path uses, where `payload` is a
+ * JSON **string**:
+ * ```json
+ * { "head": { "cmd": 65537, "cmd_status": 2, "sign_code": 0, ... },
+ *   "payload": "{\"t\":\"…\",\"protocol\":2,\"data\":{\"104\":80,\"106\":0}}" }
+ * ```
+ * Two DP layouts inside the decoded payload are handled: Tuya-native (`data.dps`) and AIoT-direct
+ * (`data` with integer-keyed DP ids). Falls back to flat `envelope.dps` / `envelope.data.dps`
+ * shapes for any pre-parsed delivery. Returns `undefined` when no recognised shape is found.
+ *
+ * @internal
+ */
+export declare function parseTuyaDpReport(raw: unknown): Record<string, unknown> | undefined;
+/**
+ * Routes validated inbound Tuya DP events to the registered {@link TuyaDpInbound} listener.
+ *
+ * Mirrors the AIoT MQTT inbound path: the transport owns parsing; the capability layer owns
+ * semantics. A malformed or empty payload is silently dropped; the listener sees only
+ * successfully parsed DP maps.
+ */
+export declare class TuyaDpRouter {
+    private listener;
+    /** Register the inbound listener. Replaces any previously registered one. */
+    setListener(listener: TuyaDpInbound): void;
+    /**
+     * Parse `dps` and, if valid, deliver it to the registered listener for `sn`.
+     * Silently drops malformed or empty payloads.
+     */
+    deliver(sn: string, dps: unknown): void;
+}

package/dist/transport/tuya/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Tuya / Thingclips cloud-protocol client.
+ *
+ * A clean, typed base for the eufy app's Tuya backbone: deterministic eufy→Tuya account derivation,
+ * exact `api.json` request assembly, the sign, and a small {@link TuyaClient}. No configuration is
+ * required — the built-in signing key ({@link TUYA_SIGN_K}) works out of the box.
+ *
+ * Quick start:
+ *
+ *   import { tuya } from "@mega-yfue/eufy-sdk";
+ *   const client = new tuya.TuyaClient();           // zero-config
+ *   await client.login(eufyUserId, phoneCode);       // derives Tuya account + logs in
+ *   const dps = await client.getDeviceDps(devId);   // read DPs with the live sid
+ *
+ *   // Or inject a previously obtained sid to skip login:
+ *   const client = new tuya.TuyaClient({ sid });
+ *
+ * STATUS:
+ *   ✅ sign = HMAC-SHA256(TUYA_SIGN_K, preimage) — reproduces a live-captured signature
+ *   ✅ chKey = "7cbfe6d8" per-appId constant
+ *   ✅ login() — username.token.get → RSA-encrypt(MD5(password)) → password.login.reg
+ *      (shadow account must be provisioned via eufy Security app first)
+ *   ✅ getDeviceDps / publishDps builders ready; publishDps gated behind allowUnverified
+ */
+export * from "./account.js";
+export * from "./sign.js";
+export * from "./request.js";
+export * from "./client.js";

package/dist/transport/tuya/request.d.ts

@@ -0,0 +1,157 @@
+/**
+ * Tuya / Thingclips `api.json` request assembly + transport.
+ *
+ * Every call is a single `POST https://a1.tuyaeu.com/api.json` (EU) whose body is
+ * **form-urlencoded plaintext params** (NOT an encrypted blob) plus a `sign`. This module builds
+ * that param map for a given action, form-encodes it, POSTs it, and parses Tuya's response
+ * envelope. The one non-plaintext piece — the `sign` digest — is delegated to a {@link TuyaSigner}.
+ */
+/** Injectable POST transport — takes (url, form-body), returns the parsed JSON envelope. Native `fetch` by default. */
+export type TuyaHttpPost = (url: string, body: string) => Promise<unknown>;
+import { type TuyaSigner } from "./sign.js";
+/** EU api.json endpoint. (Other regions swap the `tuyaeu` shard, e.g. `tuyaus`/`tuyacn`.) */
+export declare const TUYA_API_ENDPOINT = "https://a1.tuyaeu.com/api.json";
+/** Hardcoded public app key (a.k.a. clientId) shipped in the eufy app. */
+export declare const TUYA_APP_KEY = "w8x4ppqkdxvqnd73ahj9";
+/**
+ * Hardcoded app secret. Public only in the sense that it ships in the vendor app; it feeds the NATIVE
+ * sign digest (see {@link TuyaSigner}), so it is not used directly in this module.
+ */
+export declare const TUYA_APP_SECRET = "pt585qhmt75hwcynchnps9dnxh9suhwd";
+/** Thingclips SDK version the captured traffic used. */
+export declare const TUYA_SDK_VERSION = "7.5.0";
+/** App version the client reports (also feeds the sign via `appVersion`). */
+export declare const TUYA_APP_VERSION = "6.0.51_26722";
+/** A single action to call: the `a` (action) + `v` (version) + optional pre-serialized `postData`. */
+export interface TuyaAction {
+    /** Action name, e.g. `thing.m.device.dp.publish`. */
+    a: string;
+    /** Per-action version, e.g. `"1.0"` / `"2.0"`. */
+    v: string;
+    /** The `postData` param value — already a JSON STRING (Tuya carries the body as a string param). */
+    postData?: string;
+}
+/** Per-install session identity carried on every request. */
+export interface TuyaSession {
+    /** Session id from a successful login; empty string pre-login. */
+    sid: string;
+    /** Per-install device id (44-hex in the capture). See {@link TuyaClient} for generation. */
+    deviceId: string;
+    /**
+     * 8-hex `chKey`. ✅ SOLVED: `getChKey` in `libthing_security.so` is a pure
+     * function of the **appId only** (never touches time/session/Context), so it's a per-appId CONSTANT —
+     * `"7cbfe6d8"` for this app's appId. Hardcode it.
+     */
+    chKey: string;
+}
+/**
+ * The constant / environment fields of a request. All are plaintext and (except the sign-relevant
+ * `clientId`/`os`/`ttid`/`lang`/`et`/`appVersion`) do NOT feed the sign. Values marked TODO are
+ * cosmetic os-info fields whose exact contents were not pinned from the capture; they do not affect
+ * the sign and can be tuned freely.
+ */
+export interface TuyaEnv {
+    /** appKey. */
+    clientId: string;
+    sdkVersion: string;
+    appVersion: string;
+    /** "Android". */
+    os: string;
+    /** "android". */
+    ttid: string;
+    /** "en_GB". */
+    lang: string;
+    /** "3". */
+    et: string;
+    /** "gzip". */
+    cp: string;
+    /** "sdk". */
+    channel: string;
+    /** "1". */
+    nd: string;
+    /** JSON string, e.g. `{"customDomainSupport":"1","sdkInt":"36","nd":"1","brand":"google"}`. */
+    bizData: string;
+    /** TODO(unknown): device platform string; cosmetic (not in sign). */
+    platform: string;
+    /** TODO(unknown): OS system version; cosmetic (not in sign). */
+    osSystem: string;
+    /** IANA time zone id, e.g. "Europe/London". */
+    timeZoneId: string;
+    /** TODO(unknown): Thingclips device-core version; cosmetic (not in sign). */
+    deviceCoreVersion: string;
+}
+/** Default environment fields (see {@link TuyaEnv} for which are verified vs. TODO/cosmetic). */
+export declare const DEFAULT_TUYA_ENV: TuyaEnv;
+/** Inputs to {@link buildApiParams} beyond the action itself. */
+export interface BuildRequestOptions {
+    session: TuyaSession;
+    signer: TuyaSigner;
+    env?: TuyaEnv;
+    /** Override the unix-second `time` (default: now) — for deterministic builds/tests. */
+    time?: number;
+    /** Override the `requestId` uuid (default: random v4) — for deterministic builds/tests. */
+    requestId?: string;
+}
+/**
+ * Build the full form param map for an action: fills the static env + per-install session fields +
+ * generated `time`/`requestId`, computes the sign preimage over the allowlisted subset, and appends
+ * the `sign` from the signer. Returns a flat `Record<string,string>` ready to form-encode.
+ *
+ * The sign is the only step that needs a working {@link TuyaSigner}; a {@link StubSigner} throws
+ * here. Callers that only want to inspect the param shape can read {@link BuildRequestOptions} with
+ * a fake signer.
+ */
+export declare function buildApiParams(action: TuyaAction, opts: BuildRequestOptions): Record<string, string>;
+/** Tuya's standard response envelope. */
+export interface TuyaEnvelope<T = unknown> {
+    success: boolean;
+    /** Server unix-ms timestamp. */
+    t?: number;
+    /** Decoded result payload (present on success). */
+    result?: T;
+    errorCode?: string;
+    errorMsg?: string;
+    /** Occasionally present status string. */
+    status?: string;
+}
+/** Transport knobs for {@link sendApiRequest}. */
+export interface SendOptions {
+    endpoint?: string;
+    /** Inject a POST transport (default: native `fetch`). Used to stub the network in tests. */
+    http?: TuyaHttpPost;
+}
+/**
+ * Form-encode a param map and POST it to `api.json`, returning the parsed {@link TuyaEnvelope}.
+ * The body is `application/x-www-form-urlencoded` (Tuya rejects JSON here).
+ */
+export declare function sendApiRequest<T = unknown>(params: Record<string, string>, opts?: SendOptions): Promise<TuyaEnvelope<T>>;
+/**
+ * CONTROL: publish device data-points. `dps` is `{ "<dpId>": <value> }`; note it is JSON-stringified
+ * INSIDE the postData (Tuya nests the dps map as a string). Action `thing.m.device.dp.publish` v2.0.
+ */
+export declare function buildPublishDpsAction(devId: string, gwId: string, dps: Record<string, unknown>): TuyaAction;
+/**
+ * READ/dump: fetch a device's cached data-points. Action `thing.m.device.cache.dp.get` v2.0.
+ * TODO(verify): `dpCacheType` default (1) was not pinned from the capture.
+ */
+export declare function buildGetDeviceDpsAction(devId: string, dpCacheType?: number): TuyaAction;
+/**
+ * LOGIN step 1: fetch a pre-login RSA token for a Tuya uid.
+ * Wire-confirmed from the eufy Security app (`com.oceanwing.battery.cam`):
+ * wire action `smartlife.m.user.username.token.get`, v=2.0.
+ * Returns `{ token, publicKey, exponent }` (RSA-2048 modulus + exponent as decimal strings).
+ */
+export declare function buildUsernameTokenGetAction(countryCode: string, username: string): TuyaAction;
+/**
+ * LOGIN step 2: uid password login + auto-register.
+ * Wire-confirmed from the eufy Security app: wire action
+ * `smartlife.m.user.uid.password.login.reg`, v=1.0. `passwd` = hex of RSA-PKCS1-encrypt(MD5hex(aesPassword)).
+ * On success returns `{ sid, uid }`.
+ */
+export declare function buildPasswordLoginRegAction(countryCode: string, uid: string, passwd: string, token: string): TuyaAction;
+/**
+ * Older Tuya API path that auto-creates a shadow account if it does not yet exist.
+ * Used only by `tuya-login-diag.mjs` as a last-resort re-provisioning probe — not part of the
+ * normal login flow (`smartlife.m.user.username.token.get` is step 1).
+ */
+export declare function buildUidTokenCreateAction(countryCode: string, uid: string): TuyaAction;