homebridge-plugin-utils 1.35.0 → 2.0.0

package/dist/homebridge-enums.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Mirrors homebridge-core const enum values that plugins need at value-side runtime. `verbatimModuleSyntax` disallows value imports of ambient const enums, so the
+ * string contracts from homebridge's `api.d.ts` are re-declared here at value-side. This is the homebridge-core counterpart of the HAP mirrors in `ffmpeg/hap-enums.ts`:
+ * every Homebridge plugin registers for the `api` lifecycle events, so centralizing the mirror gives every consumer a single import path and a single update point if
+ * upstream `homebridge` ever changes a value.
+ *
+ * Values MUST stay in lockstep with the upstream definitions in `homebridge/.../api.d.ts`. The matching type alias lets consumers import the canonical name from one
+ * place rather than re-declaring it.
+ *
+ * @module
+ */
+import type { APIEvent as APIEventEnum } from "homebridge";
+/**
+ * String mirror of homebridge-core's `APIEvent` const enum, surfaced to plugins for `api.on(...)` lifecycle-event registration: `DID_FINISH_LAUNCHING` fires once
+ * homebridge has finished booting and initializing every plugin, and `SHUTDOWN` fires when homebridge shuts down (a regular shutdown or an unexpected crash).
+ *
+ * @category Homebridge
+ */
+export declare const APIEvent: {
+    readonly DID_FINISH_LAUNCHING: APIEventEnum.DID_FINISH_LAUNCHING;
+    readonly SHUTDOWN: APIEventEnum.SHUTDOWN;
+};
+/**
+ * Type alias re-exposing the homebridge enum under its canonical name so existing `event: APIEvent` annotations resolve through the shared module rather than a local
+ * redeclaration in each consumer.
+ *
+ * @category Homebridge
+ */
+export type APIEvent = APIEventEnum;
+//# sourceMappingURL=homebridge-enums.d.ts.map

package/dist/homebridge-enums.js

@@ -0,0 +1,17 @@
+/* Copyright(C) 2017-2026, HJD (https://github.com/hjdhjd). All rights reserved.
+ *
+ * homebridge-enums.ts: Single source of truth for the homebridge-core const enum mirrors that plugins need at runtime.
+ */
+/**
+ * String mirror of homebridge-core's `APIEvent` const enum, surfaced to plugins for `api.on(...)` lifecycle-event registration: `DID_FINISH_LAUNCHING` fires once
+ * homebridge has finished booting and initializing every plugin, and `SHUTDOWN` fires when homebridge shuts down (a regular shutdown or an unexpected crash).
+ *
+ * @category Homebridge
+ */
+export const APIEvent = {
+    // String const enum members are nominal in TypeScript: a raw string literal is not assignable to the enum member type without an explicit brand. The per-property
+    // assertions make the intent visible at each value, and the assertion fails fast if the upstream string ever changes out from under us.
+    DID_FINISH_LAUNCHING: "didFinishLaunching",
+    SHUTDOWN: "shutdown"
+};
+//# sourceMappingURL=homebridge-enums.js.map

package/dist/homebridge-enums.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"homebridge-enums.js","sourceRoot":"","sources":["../src/homebridge-enums.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAeH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAmH;IAEtI,kKAAkK;IAClK,wIAAwI;IACxI,oBAAoB,EAAE,oBAAyD;IAC/E,QAAQ,EAAE,UAAmC;CAC9C,CAAC"}

package/dist/index.d.ts

@@ -1,6 +1,12 @@
-export * from "./backpressure.js";
-export * from "./featureoptions.js";
-export * from "./mqttclient.js";
-export * from "./service.js";
-export * from "./util.js";
-export * from "./ffmpeg/index.js";
+export * from "./backpressure.ts";
+export * from "./clock-double.ts";
+export * from "./clock.ts";
+export * from "./featureOptions.ts";
+export * from "./featureOptions-docs.ts";
+export * from "./homebridge-enums.ts";
+export * from "./mqttClient.ts";
+export * from "./service.ts";
+export * from "./util.ts";
+export * from "./ffmpeg/index.ts";
+export * from "./logclient/index.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -3,9 +3,14 @@
  * index.ts: Homebridge plugin utilities.
  */
 export * from "./backpressure.js";
-export * from "./featureoptions.js";
-export * from "./mqttclient.js";
+export * from "./clock-double.js";
+export * from "./clock.js";
+export * from "./featureOptions.js";
+export * from "./featureOptions-docs.js";
+export * from "./homebridge-enums.js";
+export * from "./mqttClient.js";
 export * from "./service.js";
 export * from "./util.js";
 export * from "./ffmpeg/index.js";
+export * from "./logclient/index.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,iBAAiB,CAAC;AAChC,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC;AAC1B,cAAc,mBAAmB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,YAAY,CAAC;AAC3B,cAAc,qBAAqB,CAAC;AACpC,cAAc,0BAA0B,CAAC;AACzC,cAAc,uBAAuB,CAAC;AACtC,cAAc,iBAAiB,CAAC;AAChC,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC;AAC1B,cAAc,mBAAmB,CAAC;AAClC,cAAc,sBAAsB,CAAC"}

package/dist/logclient/auth.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Token acquisition for the Homebridge UI log client.
+ *
+ * {@link acquireToken} turns a {@link LogClientCredentials} discriminated union into a raw bearer token by talking to the homebridge-config-ui-x authentication API. Each
+ * credential arm maps to one of the server's authentication paths: a pre-acquired `token` is returned verbatim with no network call, a `password` arm posts to `POST
+ * /api/auth/login` (carrying an optional one-time passcode), and `noauth` posts to `POST /api/auth/noauth`, which the server honors only when its UI is configured with
+ * `auth: "none"`.
+ *
+ * The module's load-bearing concern beyond "get a token" is failure classification. The socket's reconnect loop re-authenticates on every reconnect, so it must be able
+ * to tell a transient fault (the server is briefly down or returned a 5xx) from a permanent one (the credentials are wrong, an OTP is required, or noauth is disabled).
+ * A transient fault should be retried with backoff; a permanent one must fail the reconnect fast so the user gets an actionable error rather than an endless retry loop
+ * against credentials that will never work. {@link acquireToken} therefore rejects with a {@link LogAuthError} whose `kind` discriminates `"permanent"` from
+ * `"transient"`, and the reconnect's `shouldRetry` predicate vetoes a retry on the permanent kind via {@link isPermanentAuthError}.
+ *
+ * The `fetch` implementation is injected (defaulting to the global `fetch`) so the whole module is exercised in tests without a live server.
+ *
+ * @module
+ */
+import type { EndpointTarget } from "./endpoints.ts";
+import type { LogClientCredentials } from "./types.ts";
+/**
+ * The classification of an authentication failure, used by the reconnect loop to decide whether to retry.
+ *
+ * - `"permanent"` - the credentials are wrong, an OTP is required, or noauth is disabled. Retrying with the same credentials will keep failing, so the reconnect loop
+ *   vetoes a retry and surfaces the error to the user.
+ * - `"transient"` - a network fault or a server-side 5xx/429. The condition may clear on its own, so the reconnect loop retries with backoff.
+ *
+ * @category Log Client
+ */
+export type LogAuthErrorKind = "permanent" | "transient";
+/**
+ * Options accepted by {@link LogAuthError}'s constructor.
+ *
+ * @property cause - The underlying cause (a network error, or the HTTP response context), attached for diagnostics.
+ * @property kind  - The failure classification. See {@link LogAuthErrorKind}.
+ *
+ * @category Log Client
+ */
+export interface LogAuthErrorOptions {
+    readonly cause?: unknown;
+    readonly kind: LogAuthErrorKind;
+}
+/**
+ * The error thrown by {@link acquireToken} when authentication fails.
+ *
+ * Carries a {@link LogAuthErrorKind} discriminator so a consumer (specifically the socket's reconnect `shouldRetry` predicate) can distinguish a permanent credential
+ * problem from a transient network/server fault without parsing the message text. The message itself is already actionable - it names the failing path and the reason -
+ * so it can be surfaced to the user directly.
+ *
+ * @category Log Client
+ */
+export declare class LogAuthError extends Error {
+    /**
+     * The failure classification. `"permanent"` failures must not be retried; `"transient"` failures may be.
+     */
+    readonly kind: LogAuthErrorKind;
+    /**
+     * Construct a new authentication error.
+     *
+     * @param message - A human-readable, actionable description of the failure.
+     * @param options - The classification and optional underlying cause. See {@link LogAuthErrorOptions}.
+     */
+    constructor(message: string, options: LogAuthErrorOptions);
+}
+/**
+ * Type guard: returns `true` when `error` is a {@link LogAuthError} classified `"permanent"`.
+ *
+ * The reconnect loop's `shouldRetry` predicate consults this to veto a retry the instant a permanent credential failure surfaces, so a wrong password or a missing OTP
+ * fails the reconnect fast rather than looping forever against credentials that cannot succeed.
+ *
+ * @param error - The value to test.
+ *
+ * @returns `true` when `error` is a permanent authentication failure.
+ *
+ * @category Log Client
+ */
+export declare function isPermanentAuthError(error: unknown): boolean;
+/**
+ * Options accepted by {@link acquireToken}: the connection target plus an injectable `fetch` seam.
+ *
+ * @property fetch - The fetch implementation to use. Defaults to the global `fetch`. Injected so the auth flow is testable without a live server.
+ * @property host  - The hostname or IP of the homebridge-config-ui-x server.
+ * @property port  - The TCP port the server listens on.
+ * @property tls   - When `true`, use the secure (`https`) scheme; when `false` or omitted, plaintext (`http`).
+ *
+ * @category Log Client
+ */
+export interface AcquireTokenOptions extends EndpointTarget {
+    readonly fetch?: typeof fetch;
+}
+/**
+ * Acquire a raw bearer token for the homebridge-config-ui-x API from the supplied credentials.
+ *
+ * Dispatches on the credential discriminated union:
+ *
+ * - `token` - returns the pre-acquired token verbatim, with no network call. A static token that has since expired is not detected here; the failure surfaces later when
+ *   the socket handshake is rejected.
+ * - `password` - posts `{ username, password, otp? }` to `POST /api/auth/login`.
+ * - `noauth` - posts to `POST /api/auth/noauth`, which the server honors only when its UI is configured with `auth: "none"`.
+ *
+ * On failure it rejects with a {@link LogAuthError} whose `kind` classifies the failure as permanent (wrong credentials, OTP required, noauth disabled, broken success
+ * body) or transient (network fault, 5xx, 429), so the reconnect loop can fail fast on permanent failures and retry transient ones.
+ *
+ * @param credentials - The credentials to authenticate with. See {@link LogClientCredentials}.
+ * @param options     - The connection target and the injectable `fetch` seam. See {@link AcquireTokenOptions}.
+ *
+ * @returns A promise resolving to the raw bearer token (the bare JWT, with no `Bearer` prefix).
+ *
+ * @throws {@link LogAuthError} on any authentication failure, classified permanent or transient.
+ *
+ * @category Log Client
+ */
+export declare function acquireToken(credentials: LogClientCredentials, options: AcquireTokenOptions): Promise<string>;
+//# sourceMappingURL=auth.d.ts.map

package/dist/logclient/auth.js

@@ -0,0 +1,199 @@
+/* Copyright(C) 2017-2026, HJD (https://github.com/hjdhjd). All rights reserved.
+ *
+ * logclient/auth.ts: Token acquisition against the homebridge-config-ui-x authentication API.
+ */
+import { formatErrorMessage } from "../util.js";
+import { httpBaseUrl } from "./endpoints.js";
+// The auth API returns these status codes for a genuine credential or precondition problem: 401 (wrong username/password, or the no-auth path used against a server not
+// in "none" mode), 403 (account disabled or action not permitted), and 412 (a one-time passcode is required but was not supplied). All three keep failing until the
+// caller changes the credentials or supplies an OTP, so they are classified permanent and the reconnect loop must not retry them. A 400 is handled separately (see
+// throwForStatus): it is a malformed-request / protocol mismatch, not a credential problem, so it carries a different message even though it too is permanent.
+const CREDENTIAL_STATUS = new Set([401, 403, 412]);
+/**
+ * The error thrown by {@link acquireToken} when authentication fails.
+ *
+ * Carries a {@link LogAuthErrorKind} discriminator so a consumer (specifically the socket's reconnect `shouldRetry` predicate) can distinguish a permanent credential
+ * problem from a transient network/server fault without parsing the message text. The message itself is already actionable - it names the failing path and the reason -
+ * so it can be surfaced to the user directly.
+ *
+ * @category Log Client
+ */
+export class LogAuthError extends Error {
+    /**
+     * The failure classification. `"permanent"` failures must not be retried; `"transient"` failures may be.
+     */
+    kind;
+    /**
+     * Construct a new authentication error.
+     *
+     * @param message - A human-readable, actionable description of the failure.
+     * @param options - The classification and optional underlying cause. See {@link LogAuthErrorOptions}.
+     */
+    constructor(message, options) {
+        super(message, { cause: options.cause });
+        this.kind = options.kind;
+        this.name = "LogAuthError";
+    }
+}
+/**
+ * Type guard: returns `true` when `error` is a {@link LogAuthError} classified `"permanent"`.
+ *
+ * The reconnect loop's `shouldRetry` predicate consults this to veto a retry the instant a permanent credential failure surfaces, so a wrong password or a missing OTP
+ * fails the reconnect fast rather than looping forever against credentials that cannot succeed.
+ *
+ * @param error - The value to test.
+ *
+ * @returns `true` when `error` is a permanent authentication failure.
+ *
+ * @category Log Client
+ */
+export function isPermanentAuthError(error) {
+    return (error instanceof LogAuthError) && (error.kind === "permanent");
+}
+// Read a token out of a successful auth response body. The server returns `{ access_token, token_type: "Bearer", expires_in }`; we need only `access_token`. A 2xx
+// response whose body is missing or malformed is treated as a permanent failure, because a server that answers a valid request with an unparseable success body will
+// not behave differently on retry - the contract is broken, not the moment.
+async function readAccessToken(response, pathLabel) {
+    let body;
+    try {
+        body = await response.json();
+    }
+    catch (error) {
+        throw new LogAuthError(pathLabel + " succeeded but returned an unreadable response body: " + formatErrorMessage(error) + ".", { cause: error, kind: "permanent" });
+    }
+    const token = isRecord(body) ? body["access_token"] : undefined;
+    if (typeof token !== "string") {
+        throw new LogAuthError(pathLabel + " succeeded but returned no access token.", { cause: body, kind: "permanent" });
+    }
+    return token;
+}
+// Narrow an unknown value to a plain record so a single top-level string property (such as `access_token` or `message`) can be read off a parsed JSON body without unsafe
+// member access.
+function isRecord(value) {
+    return (typeof value === "object") && (value !== null);
+}
+// Classify and throw for a non-2xx auth response. The status code is the discriminator: the codes in `CREDENTIAL_STATUS` describe a credential problem that will not
+// clear on retry, so they raise a permanent failure with a path-specific, actionable message; a 400 is handled separately below as a permanent protocol error, and every
+// other status (notably 5xx and 429) is treated as transient so the reconnect loop retries with backoff. The body is read best-effort for context but never required - a
+// server returning an error status with no body still produces a clear message.
+async function throwForStatus(response, pathLabel, permanentHint) {
+    const detail = await readErrorDetail(response);
+    const suffix = (detail.length > 0) ? (": " + detail) : "";
+    // A genuine credential or precondition rejection (401/403/412): the caller must change something, so surface the path-specific, actionable hint. Permanent - retrying
+    // the same credentials cannot succeed.
+    if (CREDENTIAL_STATUS.has(response.status)) {
+        throw new LogAuthError(pathLabel + " failed - " + permanentHint + suffix + ".", { cause: { status: response.status }, kind: "permanent" });
+    }
+    // A 400 is a malformed-request / protocol mismatch, not a credential problem - a server that merely is not in no-auth mode answers the no-auth path with 401, never
+    // 400. It is permanent (the identical request keeps failing) but it points at a request or homebridge-config-ui-x version mismatch rather than the credentials.
+    if (response.status === 400) {
+        throw new LogAuthError(pathLabel + " failed - the server rejected the request as malformed (HTTP 400)" + suffix +
+            "; this usually indicates a homebridge-config-ui-x version or protocol mismatch.", { cause: { status: 400 }, kind: "permanent" });
+    }
+    // Everything else (notably 5xx and 429) may clear on its own, so it is transient and the reconnect loop retries it with backoff.
+    throw new LogAuthError(pathLabel + " failed - the server returned HTTP " + response.status.toString() + " (" + response.statusText + ")" + suffix + ".", { cause: { status: response.status }, kind: "transient" });
+}
+// Best-effort read of an error response's human-readable detail. homebridge-config-ui-x typically returns `{ message, error, statusCode }` on a failure; we surface the
+// `message` when present, falling back to the raw text. A body that cannot be read at all yields an empty string so the caller's message still reads cleanly without it.
+async function readErrorDetail(response) {
+    let text;
+    try {
+        text = await response.text();
+    }
+    catch {
+        return "";
+    }
+    if (text.length === 0) {
+        return "";
+    }
+    try {
+        const parsed = JSON.parse(text);
+        const message = isRecord(parsed) ? parsed["message"] : undefined;
+        if (typeof message === "string") {
+            return message;
+        }
+    }
+    catch {
+        // Not JSON; fall through and surface the raw text trimmed of its trailing period so it composes cleanly with the caller's own trailing period.
+    }
+    return text.replace(/\.$/, "");
+}
+// Wrap a network-level fetch rejection (DNS failure, connection refused, TLS error) as a transient authentication failure. A connection that cannot be established may
+// succeed on a later attempt, so the reconnect loop should retry rather than give up.
+function networkFailure(pathLabel, error) {
+    return new LogAuthError(pathLabel + " could not reach the server: " + formatErrorMessage(error) + ".", { cause: error, kind: "transient" });
+}
+/**
+ * Acquire a raw bearer token for the homebridge-config-ui-x API from the supplied credentials.
+ *
+ * Dispatches on the credential discriminated union:
+ *
+ * - `token` - returns the pre-acquired token verbatim, with no network call. A static token that has since expired is not detected here; the failure surfaces later when
+ *   the socket handshake is rejected.
+ * - `password` - posts `{ username, password, otp? }` to `POST /api/auth/login`.
+ * - `noauth` - posts to `POST /api/auth/noauth`, which the server honors only when its UI is configured with `auth: "none"`.
+ *
+ * On failure it rejects with a {@link LogAuthError} whose `kind` classifies the failure as permanent (wrong credentials, OTP required, noauth disabled, broken success
+ * body) or transient (network fault, 5xx, 429), so the reconnect loop can fail fast on permanent failures and retry transient ones.
+ *
+ * @param credentials - The credentials to authenticate with. See {@link LogClientCredentials}.
+ * @param options     - The connection target and the injectable `fetch` seam. See {@link AcquireTokenOptions}.
+ *
+ * @returns A promise resolving to the raw bearer token (the bare JWT, with no `Bearer` prefix).
+ *
+ * @throws {@link LogAuthError} on any authentication failure, classified permanent or transient.
+ *
+ * @category Log Client
+ */
+export async function acquireToken(credentials, options) {
+    // A pre-acquired token needs no network round-trip; return it verbatim. The token arm is handled first so the common "I already have a token" path costs nothing.
+    if (credentials.kind === "token") {
+        return credentials.token;
+    }
+    const fetchImpl = options.fetch ?? fetch;
+    const base = httpBaseUrl(options);
+    switch (credentials.kind) {
+        case "noauth": {
+            // The no-authentication path. The server returns a token from `POST /api/auth/noauth` only when its UI is configured with `auth: "none"`; otherwise it rejects,
+            // which we classify permanent because the server's auth mode will not change between reconnect attempts.
+            return postForToken(fetchImpl, base + "/api/auth/noauth", undefined, "No-auth authentication", "the server does not have authentication disabled (set the UI auth mode to \"none\", or supply --user/--pass)");
+        }
+        case "password": {
+            // The interactive login path. We post the username, password, and optional OTP. A 401/403 means the credentials are wrong; a 412 means an OTP is required - both
+            // permanent until the caller supplies correct credentials or a passcode.
+            const body = { password: credentials.password, username: credentials.username };
+            if (credentials.otp !== undefined) {
+                body["otp"] = credentials.otp;
+            }
+            return postForToken(fetchImpl, base + "/api/auth/login", body, "Password authentication", "the username, password, or one-time passcode was rejected (a 2FA-enabled account requires --otp)");
+        }
+        default: {
+            // The union is exhausted above (the `token` arm returned earlier). This satisfies exhaustiveness and guards against a future credential arm being added without a
+            // handler here.
+            throw new LogAuthError("Unsupported credential kind.", { cause: credentials, kind: "permanent" });
+        }
+    }
+}
+// Issue a single POST to an auth endpoint and extract the access token, mapping every failure shape to a classified {@link LogAuthError}. A JSON body is sent when one is
+// supplied (the login path); the noauth path posts with no body. Network rejections are transient; non-2xx statuses are classified by `throwForStatus`.
+async function postForToken(fetchImpl, url, body, pathLabel, permanentHint) {
+    // The JSON content-type header is a claim that a JSON body follows, so the two are derived together from a single condition: a request that carries a body
+    // declares `application/json` and serializes it, and a bodyless request (the no-auth path) sends neither. This coupling is the single source of truth that keeps
+    // every auth POST well-formed - declaring `application/json` with no body is incoherent, and Fastify (the homebridge-config-ui-x HTTP server) rejects a
+    // declared-JSON body that is empty.
+    const init = (body !== undefined) ?
+        { body: JSON.stringify(body), headers: { "Content-Type": "application/json" }, method: "POST" } :
+        { method: "POST" };
+    let response;
+    try {
+        response = await fetchImpl(url, init);
+    }
+    catch (error) {
+        throw networkFailure(pathLabel, error);
+    }
+    if (!response.ok) {
+        return throwForStatus(response, pathLabel, permanentHint);
+    }
+    return readAccessToken(response, pathLabel);
+}
+//# sourceMappingURL=auth.js.map

package/dist/logclient/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../../src/logclient/auth.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAsBH,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAE7C,wKAAwK;AACxK,oKAAoK;AACpK,mKAAmK;AACnK,+JAA+J;AAC/J,MAAM,iBAAiB,GAAG,IAAI,GAAG,CAAS,CAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAE,CAAC,CAAC;AA2B7D;;;;;;;;GAQG;AACH,MAAM,OAAO,YAAa,SAAQ,KAAK;IAErC;;OAEG;IACa,IAAI,CAAmB;IAEvC;;;;;OAKG;IACH,YAAmB,OAAe,EAAE,OAA4B;QAE9D,KAAK,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC;QACzC,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;QACzB,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;IAC7B,CAAC;CACF;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,oBAAoB,CAAC,KAAc;IAEjD,OAAO,CAAC,KAAK,YAAY,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,KAAK,WAAW,CAAC,CAAC;AACzE,CAAC;AAiBD,mKAAmK;AACnK,qKAAqK;AACrK,4EAA4E;AAC5E,KAAK,UAAU,eAAe,CAAC,QAAkB,EAAE,SAAiB;IAElE,IAAI,IAAa,CAAC;IAElB,IAAI,CAAC;QAEH,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;IAC/B,CAAC;IAAC,OAAM,KAAc,EAAE,CAAC;QAEvB,MAAM,IAAI,YAAY,CAAC,SAAS,GAAG,uDAAuD,GAAG,kBAAkB,CAAC,KAAK,CAAC,GAAG,GAAG,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC,CAAC;IACrK,CAAC;IAED,MAAM,KAAK,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAEhE,IAAG,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAE7B,MAAM,IAAI,YAAY,CAAC,SAAS,GAAG,0CAA0C,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC,CAAC;IACrH,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAED,0KAA0K;AAC1K,iBAAiB;AACjB,SAAS,QAAQ,CAAC,KAAc;IAE9B,OAAO,CAAC,OAAO,KAAK,KAAK,QAAQ,CAAC,IAAI,CAAC,KAAK,KAAK,IAAI,CAAC,CAAC;AACzD,CAAC;AAED,qKAAqK;AACrK,yKAAyK;AACzK,yKAAyK;AACzK,gFAAgF;AAChF,KAAK,UAAU,cAAc,CAAC,QAAkB,EAAE,SAAiB,EAAE,aAAqB;IAExF,MAAM,MAAM,GAAG,MAAM,eAAe,CAAC,QAAQ,CAAC,CAAC;IAC/C,MAAM,MAAM,GAAG,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAE1D,sKAAsK;IACtK,uCAAuC;IACvC,IAAG,iBAAiB,CAAC,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;QAE1C,MAAM,IAAI,YAAY,CAAC,SAAS,GAAG,YAAY,GAAG,aAAa,GAAG,MAAM,GAAG,GAAG,EAAE,EAAE,KAAK,EAAE,EAAE,MAAM,EAAE,QAAQ,CAAC,MAAM,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC,CAAC;IAC7I,CAAC;IAED,oKAAoK;IACpK,gKAAgK;IAChK,IAAG,QAAQ,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;QAE3B,MAAM,IAAI,YAAY,CAAC,SAAS,GAAG,mEAAmE,GAAG,MAAM;YAC7G,iFAAiF,EAAE,EAAE,KAAK,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC,CAAC;IACtI,CAAC;IAED,iIAAiI;IACjI,MAAM,IAAI,YAAY,CAAC,SAAS,GAAG,qCAAqC,GAAG,QAAQ,CAAC,MAAM,CAAC,QAAQ,EAAE,GAAG,IAAI,GAAG,QAAQ,CAAC,UAAU,GAAG,GAAG,GAAG,MAAM,GAAG,GAAG,EACrJ,EAAE,KAAK,EAAE,EAAE,MAAM,EAAE,QAAQ,CAAC,MAAM,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC,CAAC;AAC/D,CAAC;AAED,wKAAwK;AACxK,yKAAyK;AACzK,KAAK,UAAU,eAAe,CAAC,QAAkB;IAE/C,IAAI,IAAY,CAAC;IAEjB,IAAI,CAAC;QAEH,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;IAC/B,CAAC;IAAC,MAAM,CAAC;QAEP,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,IAAG,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAErB,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,IAAI,CAAC;QAEH,MAAM,MAAM,GAAY,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACzC,MAAM,OAAO,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QAEjE,IAAG,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;YAE/B,OAAO,OAAO,CAAC;QACjB,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QAEP,+IAA+I;IACjJ,CAAC;IAED,OAAO,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;AACjC,CAAC;AAED,uKAAuK;AACvK,sFAAsF;AACtF,SAAS,cAAc,CAAC,SAAiB,EAAE,KAAc;IAEvD,OAAO,IAAI,YAAY,CAAC,SAAS,GAAG,+BAA+B,GAAG,kBAAkB,CAAC,KAAK,CAAC,GAAG,GAAG,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC,CAAC;AAC9I,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,WAAiC,EAAE,OAA4B;IAEhG,kKAAkK;IAClK,IAAG,WAAW,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;QAEhC,OAAO,WAAW,CAAC,KAAK,CAAC;IAC3B,CAAC;IAED,MAAM,SAAS,GAAG,OAAO,CAAC,KAAK,IAAI,KAAK,CAAC;IACzC,MAAM,IAAI,GAAG,WAAW,CAAC,OAAO,CAAC,CAAC;IAElC,QAAO,WAAW,CAAC,IAAI,EAAE,CAAC;QAExB,KAAK,QAAQ,CAAC,CAAC,CAAC;YAEd,gKAAgK;YAChK,yGAAyG;YACzG,OAAO,YAAY,CAAC,SAAS,EAAE,IAAI,GAAG,kBAAkB,EAAE,SAAS,EAAE,wBAAwB,EAC3F,8GAA8G,CAAC,CAAC;QACpH,CAAC;QAED,KAAK,UAAU,CAAC,CAAC,CAAC;YAEhB,iKAAiK;YACjK,yEAAyE;YACzE,MAAM,IAAI,GAA2B,EAAE,QAAQ,EAAE,WAAW,CAAC,QAAQ,EAAE,QAAQ,EAAE,WAAW,CAAC,QAAQ,EAAE,CAAC;YAExG,IAAG,WAAW,CAAC,GAAG,KAAK,SAAS,EAAE,CAAC;gBAEjC,IAAI,CAAC,KAAK,CAAC,GAAG,WAAW,CAAC,GAAG,CAAC;YAChC,CAAC;YAED,OAAO,YAAY,CAAC,SAAS,EAAE,IAAI,GAAG,iBAAiB,EAAE,IAAI,EAAE,yBAAyB,EACtF,kGAAkG,CAAC,CAAC;QACxG,CAAC;QAED,OAAO,CAAC,CAAC,CAAC;YAER,kKAAkK;YAClK,gBAAgB;YAChB,MAAM,IAAI,YAAY,CAAC,8BAA8B,EAAE,EAAE,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC,CAAC;QACpG,CAAC;IACH,CAAC;AACH,CAAC;AAED,0KAA0K;AAC1K,wJAAwJ;AACxJ,KAAK,UAAU,YAAY,CAAC,SAAuB,EAAE,GAAW,EAAE,IAAwC,EAAE,SAAiB,EAAE,aAAqB;IAElJ,2JAA2J;IAC3J,iKAAiK;IACjK,wJAAwJ;IACxJ,oCAAoC;IACpC,MAAM,IAAI,GAAgB,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC;QAC9C,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;QACjG,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;IAErB,IAAI,QAAkB,CAAC;IAEvB,IAAI,CAAC;QAEH,QAAQ,GAAG,MAAM,SAAS,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;IACxC,CAAC;IAAC,OAAM,KAAc,EAAE,CAAC;QAEvB,MAAM,cAAc,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC;IACzC,CAAC;IAED,IAAG,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;QAEhB,OAAO,cAAc,CAAC,QAAQ,EAAE,SAAS,EAAE,aAAa,CAAC,CAAC;IAC5D,CAAC;IAED,OAAO,eAAe,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;AAC9C,CAAC"}

package/dist/logclient/cli-run.d.ts

@@ -0,0 +1,76 @@
+import type { LogSocketFactory } from "./socket.ts";
+/**
+ * The event-hook shape {@link CliStream} exposes for the stream events the CLI observes. Modeled as an overloaded call signature - the same shape `EventEmitter.on`/
+ * `off` present - so each event's listener is typed to exactly what that event delivers: `"error"` hands the listener the failing error (an `EPIPE` broken pipe, or a
+ * genuine write fault such as `ENOSPC`), while `"drain"` delivers nothing and merely signals that the writable buffer has fallen back below its high-water mark.
+ *
+ * @category Log Client
+ */
+export interface CliStreamEventHook {
+    (event: "drain", listener: () => void): void;
+    (event: "error", listener: (error: NodeJS.ErrnoException) => void): void;
+}
+/**
+ * A minimal output-stream surface {@link runHblog} writes to. Models the subset of a Node `WriteStream` the CLI actually uses: `write` for output, the optional `isTTY`
+ * flag that drives the auto-color decision, and the optional `on`/`off` event hooks used to trap a broken-pipe (`EPIPE`) error and to await `drain` when a write reports
+ * backpressure. The narrow interface keeps a test sink small (a `write` function is enough) while `process.stdout`/`process.stderr` satisfy it structurally.
+ *
+ * @category Log Client
+ */
+export interface CliStream {
+    isTTY?: boolean;
+    off?: CliStreamEventHook;
+    on?: CliStreamEventHook;
+    write: (chunk: string) => boolean;
+}
+/**
+ * Options accepted by {@link runHblog}. Every external dependency the CLI touches is an injected seam, so the whole flow runs deterministically in tests.
+ *
+ * @property argv          - The argument vector (typically `process.argv.slice(2)`).
+ * @property cwd           - The current working directory. Reserved for future relative-path resolution; the home directory is the config-file anchor today.
+ * @property env           - The environment map (typically `process.env`).
+ * @property fetch         - Optional `fetch` seam forwarded to the engine's auth and REST transports. Defaults to the global `fetch`.
+ * @property homedir       - The user's home directory, used to locate `~/.hblog.json` unless `HBLOG_CONFIG` overrides the path.
+ * @property now           - Optional wall-clock epoch source (milliseconds) used to resolve the `--since`/`--until` time-range expressions against a single deterministic
+ *                           instant. Defaults to `systemClock.now`; a test injects a fixed clock so a windowed run's bounds are reproducible.
+ * @property readFile      - Optional file-read seam forwarded to the config loader and used to read the package version. Defaults to `node:fs/promises` `readFile`.
+ * @property socketFactory - Optional socket-factory seam forwarded to the engine, so a test drives the live tail without a WebSocket. Defaults to the real factory.
+ * @property stat          - Optional file-stat seam forwarded to the config loader for the permissions warning. Defaults to `node:fs/promises` `stat`.
+ * @property stderr        - The diagnostics/warnings stream. Production passes `process.stderr`.
+ * @property stdout        - The log-data stream. Production passes `process.stdout`.
+ *
+ * @category Log Client
+ */
+export interface RunHblogOptions {
+    readonly argv: readonly string[];
+    readonly cwd: string;
+    readonly env: NodeJS.ProcessEnv;
+    readonly fetch?: typeof fetch;
+    readonly homedir: string;
+    readonly now?: () => number;
+    readonly readFile?: (path: string) => Promise<string>;
+    readonly socketFactory?: LogSocketFactory;
+    readonly stat?: (path: string) => Promise<{
+        readonly mode: number;
+    }>;
+    readonly stderr: CliStream;
+    readonly stdout: CliStream;
+}
+/**
+ * Run the `hblog` command-line flow and return the process exit code.
+ *
+ * Parses {@link RunHblogOptions.argv}, handles `--help`/`--version` immediately, resolves the connection across flags / environment / `~/.hblog.json` (honoring
+ * `HBLOG_CONFIG`), maps the result into a {@link LogClientCredentials} and a {@link TailRequest}, builds a {@link HomebridgeLogClient}, runs the selected channel,
+ * applies the {@link createLogFilter} criteria, and writes log data to stdout (NDJSON for `--json`, raw/stripped lines otherwise) while routing diagnostics and warnings
+ * to stderr. A SIGINT/SIGTERM aborts the run cleanly (exit 0); a broken pipe (`EPIPE`) on stdout also ends cleanly (exit 0); a usage error returns 2; a connection or
+ * authentication failure returns 1. Token redaction is applied at the hard-error stderr writes (the setup failure, a captured stdout write error on either the
+ * normal-completion or the catch path, and the streaming catch's generic error); the usage and advisory writes never carry a token.
+ *
+ * @param options - The injected argument vector, environment, streams, directories, and seams. See {@link RunHblogOptions}.
+ *
+ * @returns The process exit code: 0 success / clean signal / help / version, 1 connection or auth failure, 2 usage error.
+ *
+ * @category Log Client
+ */
+export declare function runHblog(options: RunHblogOptions): Promise<number>;
+//# sourceMappingURL=cli-run.d.ts.map