@hue-run/sdk 0.9.0 → 0.11.0

package/dist/cli/listen.d.ts

@@ -0,0 +1,76 @@
+import { lookup as dnsLookup } from "node:dns";
+/**
+ * `hue listen`: delivers a simulated world's events to a receiver on this machine, the way a
+ * provider would post them to a public request URL. The client pulls leased deliveries from Hue
+ * with the subscription's own credential (a world token or a connection key, never a project
+ * key), forwards each stored request unchanged to the local URL, and acknowledges it with the
+ * local answer. Every pull is one bounded request; nothing holds a connection open. A delivery is
+ * acknowledged only after the receiver answered or its window closed, so stopping never marks an
+ * event delivered that was not: an unacknowledged lease lapses and Hue retries it on the
+ * provider's schedule.
+ */
+/** Streams, environment, network and signal seams for {@link runListenCommand}; tests inject these. */
+export interface ListenCommandIo {
+    stdout?: NodeJS.WritableStream;
+    stderr?: NodeJS.WritableStream;
+    env?: NodeJS.ProcessEnv;
+    cwd?: string;
+    fetch?: typeof fetch;
+    /** Registers the stop request (SIGINT and SIGTERM by default) and returns its removal. */
+    onInterrupt?: (listener: () => void) => () => void;
+    /** The acknowledgement window a forward waits for; the provider's three seconds by default. */
+    forwardTimeoutMs?: number;
+    /** Delays between retries of a failed pull. */
+    retryDelaysMs?: readonly number[];
+}
+export declare const LISTEN_USAGE = "Usage: hue listen --subscription ID --forward-to URL [--origin URL] [--env-path PATH]\n                  [--credential world-token|connection-key] [--max N] [--allow-remote-forward]\n\nDeliver a simulated world's events to a receiver on this machine. Hue's signed requests (Slack\nEvents API requests today) are pulled with the subscription's own credential, forwarded unchanged\nto --forward-to, and acknowledged with the receiver's answer. Press Ctrl+C to stop: pulls stop,\ndeliveries in flight are finished and acknowledged, and nothing unanswered is acknowledged.\n\nThe credential is read from the environment, never from the command line:\n  HUE_WORLD_TOKEN     the world token, for a subscription on one world\n  HUE_CONNECTION_KEY  the connection key, for a subscription on a connection key\nA project key (HUE_API_KEY, HUE_MCP_KEY) is refused.\n\nOptions:\n  --subscription ID       The listen subscription to deliver (its id from Hue)\n  --forward-to URL        The local receiver, for example http://localhost:3000/slack/events\n  --origin URL            Hue origin (default HUE_BASE_URL, then https://app.hue.run)\n  --env-path PATH         Load a dotenv file first (--env-file also works when it exists)\n  --credential KIND       world-token or connection-key, when both variables are set\n  --max N                 Deliveries leased per pull and forwarded at once, 1 to 10 (default 10)\n  --allow-remote-forward  Allow a --forward-to host other than this machine, over https only\n  -h, --help              Show this help";
+/** A leased delivery: the exact request the provider would send. */
+interface Delivery {
+    deliveryId: string;
+    eventId: string | null;
+    kind: "url_verification" | "event_callback";
+    retryNum: number;
+    /** The lease's end as the server stated it, or null when absent. */
+    leaseExpiresAt: number | null;
+    request: {
+        headers: Record<string, string>;
+        body: string;
+    };
+}
+/** The local answer, in the acknowledgement's own shape. */
+interface LocalAnswer {
+    outcome: "response" | "timeout" | "connection_failed" | "tls_error";
+    status?: number;
+    durationMs: number;
+    noRetry?: boolean;
+    body?: string;
+}
+/** A loopback address: 127.0.0.0/8, ::1, or 127.0.0.0/8 carried in IPv4-mapped IPv6. */
+export declare function isLoopbackAddress(address: string): boolean;
+/**
+ * The receiver URL, or why it is refused: HTTP or HTTPS without credentials or fragment, on this
+ * machine (`localhost`, a `.localhost` name or a loopback address) unless `allowRemote`, and then
+ * HTTPS only off this machine.
+ */
+export declare function parseForwardTarget(value: string, allowRemote: boolean): URL | string;
+/**
+ * Sends one delivery to the receiver and reports its answer, or null when `signal` abandoned it.
+ * The body bytes and every header go out unchanged (the provider's signature covers them), no
+ * redirect is followed, and the answer counts only inside `timeoutMs`. Only a URL verification's
+ * successful answer body is read.
+ */
+export declare function forwardDelivery(target: URL, delivery: Delivery, options?: {
+    timeoutMs?: number;
+    allowRemote?: boolean;
+    signal?: AbortSignal;
+    /** Resolves `--forward-to` names; tests stand in for DNS. */
+    resolver?: typeof dnsLookup;
+}): Promise<LocalAnswer | null>;
+/** One delivery from a pull answer, or null when it is not one this client can forward safely. */
+export declare function parseDelivery(value: unknown, subscriptionId: string): Delivery | null;
+/**
+ * Runs `hue listen` and returns the process exit code: 0 stopped, 1 failed, 2 usage error, 130
+ * interrupted twice (acknowledgements abandoned). `argv` may start with the `listen` command word.
+ */
+export declare function runListenCommand(argv: string[], io?: ListenCommandIo): Promise<number>;
+export {};