@indigoai-us/hq-cloud 5.26.0 → 5.28.0

package/src/sync/push-transport.ts

@@ -31,7 +31,7 @@
  * @indigoai-us/hq-cloud (Path B) per project event-driven-sync-menubar US-007.
  */
 
-import type { PushEvent } from "./push-event.js";
+import { encodePushEvent, type PushEvent } from "./push-event.js";
 
 export interface PushTransport {
   /** Open sockets, refresh tokens. Awaited before the watcher starts. */
@@ -82,3 +82,150 @@ export class NoopPushTransport implements PushTransport {
     this._connected = false;
   }
 }
+
+// ─── HttpPushTransport ───────────────────────────────────────────────────────
+
+/**
+ * Minimal fetch surface so tests can inject a mocked `fetch` without pulling
+ * in DOM/undici types. Matches the subset of the global `fetch` we use.
+ */
+export type FetchLike = (
+  input: string,
+  init?: {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+    signal?: AbortSignal;
+  },
+) => Promise<{ ok: boolean; status: number; text(): Promise<string> }>;
+
+/**
+ * Async getter for the current Cognito access token. Long-running daemons MUST
+ * pass a getter (not a captured string) so each publish resolves the freshest
+ * token — mirrors {@link VaultServiceConfig.authToken} semantics in types.ts.
+ * A static string is also accepted for short-lived tools and tests.
+ */
+export type AuthTokenSource = string | (() => string | Promise<string>);
+
+export interface HttpPushTransportOptions {
+  /**
+   * Vault API base URL (e.g. `https://vault-api.example.com`). The same
+   * `apiUrl` the runner already resolves for VaultClient. Trailing slashes
+   * are stripped. Required — config/env-driven, no hard-coded default.
+   */
+  apiUrl: string;
+  /**
+   * Endpoint path the PushEvent is POSTed to. Defaults to `/sync/push`
+   * (matches the deployed hq-pro endpoint from US-006). Override for testing
+   * or future endpoint moves.
+   */
+  pushPath?: string;
+  /** Cognito JWT — static string OR async getter. See {@link AuthTokenSource}. */
+  authToken: AuthTokenSource;
+  /**
+   * Optional extra headers (e.g. client identification) merged onto every
+   * request. Authorization + Content-Type are always set by the transport.
+   */
+  headers?: Record<string, string>;
+  /**
+   * Per-request timeout in milliseconds. Default 10_000. On timeout the
+   * publish rejects — the daemon treats a rejected publish as a transient
+   * miss (the cadence poll still covers it) and MUST NOT crash.
+   */
+  timeoutMs?: number;
+  /** Injectable fetch (tests). Defaults to the global `fetch`. */
+  fetchImpl?: FetchLike;
+}
+
+/**
+ * Real client `PushTransport` that POSTs encoded PushEvents to the deployed
+ * `/sync/push` endpoint, authenticating with the menubar's existing Cognito
+ * bearer token — the same auth path VaultClient uses (Authorization: Bearer
+ * <accessToken>, token resolved per-request via the supplied getter so it
+ * self-heals across refreshes).
+ *
+ * Failure posture
+ * ───────────────
+ * `publish()` rejects on a network error, a non-2xx response, or a timeout.
+ * The DAEMON is responsible for not letting that rejection crash it — the
+ * watcher's emit path catches publish errors and logs them; the periodic
+ * cadence poll remains the safety net that eventually ships the change. This
+ * transport never swallows errors itself, so callers retain full visibility.
+ *
+ * `connected` flips true on `start()` and false on `dispose()`. It is purely
+ * advisory (HTTP is connectionless); the health endpoint may read it but it
+ * carries no delivery guarantee.
+ */
+export class HttpPushTransport implements PushTransport {
+  private readonly apiUrl: string;
+  private readonly pushPath: string;
+  private readonly getAuthToken: () => Promise<string>;
+  private readonly extraHeaders: Record<string, string>;
+  private readonly timeoutMs: number;
+  private readonly fetchImpl: FetchLike;
+  private _connected = false;
+
+  constructor(opts: HttpPushTransportOptions) {
+    if (!opts.apiUrl || opts.apiUrl.trim() === "") {
+      throw new Error("HttpPushTransport: apiUrl is required");
+    }
+    this.apiUrl = opts.apiUrl.replace(/\/+$/, "");
+    const path = opts.pushPath ?? "/sync/push";
+    this.pushPath = path.startsWith("/") ? path : `/${path}`;
+    const tok = opts.authToken;
+    // Normalize string|getter into a single async getter (mirrors VaultClient).
+    this.getAuthToken =
+      typeof tok === "function" ? async () => tok() : async () => tok;
+    this.extraHeaders = opts.headers ?? {};
+    this.timeoutMs = opts.timeoutMs ?? 10_000;
+    // Bind so a destructured global fetch keeps its receiver.
+    this.fetchImpl =
+      opts.fetchImpl ??
+      ((input, init) => (globalThis.fetch as unknown as FetchLike)(input, init));
+  }
+
+  get connected(): boolean {
+    return this._connected;
+  }
+
+  async start(): Promise<void> {
+    this._connected = true;
+  }
+
+  async publish(event: PushEvent): Promise<void> {
+    // Validate-on-encode (US-007 contract) — a malformed event throws a typed
+    // PushEventDecodeError BEFORE we hit the network.
+    const body = encodePushEvent(event);
+    const token = await this.getAuthToken();
+
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    try {
+      const res = await this.fetchImpl(`${this.apiUrl}${this.pushPath}`, {
+        method: "POST",
+        headers: {
+          ...this.extraHeaders,
+          Authorization: `Bearer ${token}`,
+          "Content-Type": "application/json",
+          Accept: "application/json",
+        },
+        body,
+        signal: controller.signal,
+      });
+      if (!res.ok) {
+        const text = await res.text().catch(() => "");
+        throw new Error(
+          `HttpPushTransport: POST ${this.pushPath} failed (${res.status})${
+            text ? `: ${text}` : ""
+          }`,
+        );
+      }
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  async dispose(): Promise<void> {
+    this._connected = false;
+  }
+}