@indigoai-us/hq-cloud 6.15.0 → 6.15.2

package/src/sync/push-transport.ts

@@ -1,231 +0,0 @@
-/**
- * PushTransport — outbound shipping seam for the watcher daemon.
- *
- * The daemon wires file-watcher events into a transport that ships each
- * PushEvent to the cloud. Defining the interface here lets the daemon ship
- * with a swappable boundary — tests inject a fake, a later story swaps in a
- * concrete WebSocket/HTTP implementation, and the daemon entry point never
- * changes.
- *
- * Lifecycle
- * ─────────
- *  - `start()` is awaited BEFORE the watcher is started. It's the place
- *    to open sockets, refresh tokens, etc.
- *  - `publish(event)` is called for every coalesced PushEvent the watcher
- *    emits. Implementations decide whether to buffer, batch, or send
- *    inline; the daemon awaits the returned promise so back-pressure can
- *    be honored.
- *  - `dispose()` is awaited DURING shutdown, AFTER the watcher has been
- *    torn down. Implementations should drain in-flight publishes (with
- *    their own internal timeout) and close any sockets.
- *  - `connected` is a passive boolean used by the health endpoint. It MAY
- *    flap during reconnect attempts — that's fine; consumers treat it as
- *    advisory, not a contract.
- *
- * The `NoopPushTransport` shipped here is the default when no transport
- * is wired in: it counts publishes (so unit tests can assert delivery)
- * and logs nothing — observers should rely on the watcher's `onEvent`
- * counter on the daemon side, not the transport's internals.
- *
- * Ported from indigoai-us/hq-pro PR #112 (src/sync/push-transport.ts) into
- * @indigoai-us/hq-cloud (Path B) per project event-driven-sync-menubar US-007.
- */
-
-import { encodePushEvent, type PushEvent } from "./push-event.js";
-
-export interface PushTransport {
-  /** Open sockets, refresh tokens. Awaited before the watcher starts. */
-  start(): Promise<void>;
-  /** Ship one coalesced PushEvent. Awaited per event for back-pressure. */
-  publish(event: PushEvent): Promise<void>;
-  /** Drain + close. Awaited during daemon shutdown after watcher.dispose. */
-  dispose(): Promise<void>;
-  /** Advisory: is the transport currently believed to be connected? */
-  readonly connected: boolean;
-}
-
-/**
- * Default `PushTransport` used until a real implementation lands.
- *
- * Behavior:
- *  - `start()` flips `connected` to true.
- *  - `publish()` increments a counter (visible via `publishedCount`).
- *  - `dispose()` flips `connected` back to false.
- *
- * Deliberately silent: when the daemon runs with this default, the
- * watcher's per-event log line (emitted by the daemon itself, not the
- * transport) is the only observability. That keeps the noop from drowning
- * the log when high-rate writes hit a dev machine.
- */
-export class NoopPushTransport implements PushTransport {
-  private _connected = false;
-  private _count = 0;
-
-  get connected(): boolean {
-    return this._connected;
-  }
-
-  /** Test/observability hook: how many events have been published. */
-  get publishedCount(): number {
-    return this._count;
-  }
-
-  async start(): Promise<void> {
-    this._connected = true;
-  }
-
-  async publish(_event: PushEvent): Promise<void> {
-    this._count += 1;
-  }
-
-  async dispose(): Promise<void> {
-    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;
-  }
-}

package/src/sync/realtime-rollout.test.ts

@@ -1,86 +0,0 @@
-import { describe, expect, it, vi } from "vitest";
-
-import {
-  MAX_REALTIME_ROLLOUT_CACHE_MS,
-  RealtimeRolloutClient,
-  parseRealtimeInventory,
-  type RealtimeCapabilityVector,
-} from "./realtime-rollout.js";
-
-const capability: RealtimeCapabilityVector = {
-  hqCloud: "6.14.49",
-  hqDesktop: "none",
-  protocol: 2,
-  journal: 3,
-  durableApply: 1,
-};
-
-function jsonResponse(body: unknown, status = 200) {
-  return { ok: status >= 200 && status < 300, status, text: async () => JSON.stringify(body) };
-}
-
-function request(overrides: Partial<Parameters<RealtimeRolloutClient["inventory"]>[0]> = {}) {
-  return {
-    bearer: "token-a",
-    deviceId: "machine_a",
-    capabilityVector: capability,
-    configurationFingerprint: "config-a",
-    scopeFingerprint: "personal:prs_1",
-    ...overrides,
-  };
-}
-
-const readyInventory = {
-  scopes: [{ scopeUid: "prs_1", scopeHandle: "handle_1", scopeRevision: "rev_1", state: "v2-ready", cursor: "cursor_1" }],
-};
-
-describe("RealtimeRolloutClient", () => {
-  it("never reuses a cached positive across bearer, configuration, or scope changes", async () => {
-    let now = 1_000;
-    const requests: Array<{ headers?: Record<string, string> }> = [];
-    const fetchImpl = async (_url: string, init?: { headers?: Record<string, string> }) => {
-      requests.push({ headers: init?.headers });
-      return jsonResponse(readyInventory);
-    };
-    const client = new RealtimeRolloutClient({ apiUrl: "https://api.example/", fetchImpl, now: () => now });
-
-    await client.inventory(request());
-    await client.inventory(request());
-    await client.inventory(request({ bearer: "token-b" }));
-    await client.inventory(request({ configurationFingerprint: "config-b" }));
-    await client.inventory(request({ scopeFingerprint: "company:cmp_1" }));
-    now += MAX_REALTIME_ROLLOUT_CACHE_MS;
-    await client.inventory(request());
-
-    expect(requests).toHaveLength(5);
-    expect(requests[0]?.headers).toMatchObject({
-      Authorization: "Bearer token-a",
-      "X-HQ-Sync-Contract": "2",
-      "X-HQ-Device-ID": "machine_a",
-      "X-HQ-Cloud-Version": "6.14.49",
-      "X-HQ-Desktop-Version": "none",
-      "X-HQ-Sync-Journal": "3",
-      "X-HQ-Sync-Durable-Apply": "1",
-    });
-  });
-
-  it("fails closed for malformed or non-explicit legacy inventory", () => {
-    expect(() => parseRealtimeInventory({ scopes: [{ scopeUid: "prs_1", scopeHandle: "h", scopeRevision: "r", state: "legacy", v1Allowed: false }] })).toThrow("legacy must explicitly allow v1");
-    expect(() => parseRealtimeInventory({ scopes: [{ scopeUid: "prs_1", scopeHandle: "h", scopeRevision: "r", state: "v2-ready", cursor: "c", surprise: true }] })).toThrow("unknown field");
-    expect(() => parseRealtimeInventory({ scopes: [{ scopeUid: "prs_1", scopeHandle: "h", scopeRevision: "r", state: "unknown" }] })).toThrow("unsupported scope state");
-  });
-
-  it("rejects cache durations greater than the protocol maximum", () => {
-    expect(() => new RealtimeRolloutClient({ apiUrl: "https://api.example", maxCacheAgeMs: MAX_REALTIME_ROLLOUT_CACHE_MS + 1 })).toThrow("maxCacheAgeMs");
-  });
-
-  it("honors transitional retryAfterMs instead of holding a stale negative state", async () => {
-    const fetchImpl = vi.fn(async () => jsonResponse({ scopes: [
-      { scopeUid: "prs_1", scopeHandle: "handle_1", scopeRevision: "rev_1", state: "restoring", retryAfterMs: 0 },
-    ] }));
-    const client = new RealtimeRolloutClient({ apiUrl: "https://api.example", fetchImpl });
-    await client.inventory(request());
-    await client.inventory(request());
-    expect(fetchImpl).toHaveBeenCalledTimes(2);
-  });
-});

package/src/sync/realtime-rollout.ts

@@ -1,262 +0,0 @@
-import type { AuthTokenSource, FetchLike } from "./push-transport.js";
-
-export const REALTIME_SYNC_CONTRACT_VERSION = 2 as const;
-export const MAX_REALTIME_ROLLOUT_CACHE_MS = 30_000;
-export const DEFAULT_REALTIME_AUTHORIZATION_TIMEOUT_MS = 15_000;
-
-export interface RealtimeCapabilityVector {
-  hqCloud: string;
-  hqDesktop: string | "none";
-  protocol: 2;
-  journal: number;
-  durableApply: number;
-}
-
-export type RealtimeInventoryState =
-  | { state: "legacy"; v1Allowed: true }
-  | { state: "qualifying" | "frozen" | "seeding"; retryAfterMs: number }
-  | { state: "bootstrap-required"; snapshotDescriptorId: string }
-  | { state: "v2-ready"; cursor: string }
-  | { state: "paused"; reasonCode: string }
-  | { state: "reset-required"; resetId: string; snapshotDescriptorId: string }
-  | { state: "revoked"; localMaterialPolicy: string }
-  | { state: "restoring"; retryAfterMs: number }
-  | { state: "blocked"; reasonCode: string };
-
-export type RealtimeInventoryGrant = RealtimeInventoryState & {
-  scopeUid: string;
-  scopeHandle: string;
-  scopeRevision: string;
-};
-
-export interface RealtimeInventory {
-  scopes: readonly RealtimeInventoryGrant[];
-}
-
-export interface RealtimeInventoryRequest {
-  /** A changed token must never reuse a positive inventory result. */
-  bearer: string;
-  deviceId: string;
-  capabilityVector: RealtimeCapabilityVector;
-  /** Identifies the active client configuration/capability selection. */
-  configurationFingerprint: string;
-  /** Identifies the scopes this guarded pass is about to touch. */
-  scopeFingerprint: string;
-}
-
-export interface RealtimeRolloutClientOptions {
-  apiUrl: string;
-  fetchImpl?: FetchLike;
-  now?: () => number;
-  maxCacheAgeMs?: number;
-  authorizationTimeoutMs?: number;
-}
-
-interface CachedInventory {
-  expiresAt: number;
-  value: RealtimeInventory;
-}
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
-function nonEmpty(value: unknown, field: string): string {
-  if (typeof value !== "string" || value.trim() === "") {
-    throw new Error(`realtime inventory: ${field} must be a non-empty string`);
-  }
-  return value;
-}
-
-function exactKeys(value: Record<string, unknown>, allowed: readonly string[], label: string): void {
-  if (Object.keys(value).some((key) => !allowed.includes(key))) {
-    throw new Error(`realtime inventory: ${label} contains an unknown field`);
-  }
-}
-
-function parseState(value: unknown): RealtimeInventoryState {
-  if (!isRecord(value) || typeof value.state !== "string") {
-    throw new Error("realtime inventory: scope state is invalid");
-  }
-  switch (value.state) {
-    case "legacy":
-      exactKeys(value, ["state", "v1Allowed"], "legacy state");
-      if (value.v1Allowed !== true) throw new Error("realtime inventory: legacy must explicitly allow v1");
-      return { state: "legacy", v1Allowed: true };
-    case "qualifying":
-    case "frozen":
-    case "seeding":
-    case "restoring":
-      exactKeys(value, ["state", "retryAfterMs"], `${value.state} state`);
-      if (
-        typeof value.retryAfterMs !== "number" ||
-        !Number.isSafeInteger(value.retryAfterMs) ||
-        value.retryAfterMs < 0
-      ) {
-        throw new Error(`realtime inventory: ${value.state} retryAfterMs is invalid`);
-      }
-      return { state: value.state, retryAfterMs: value.retryAfterMs };
-    case "bootstrap-required":
-      exactKeys(value, ["state", "snapshotDescriptorId"], "bootstrap-required state");
-      return { state: value.state, snapshotDescriptorId: nonEmpty(value.snapshotDescriptorId, "snapshotDescriptorId") };
-    case "v2-ready":
-      exactKeys(value, ["state", "cursor"], "v2-ready state");
-      return { state: value.state, cursor: nonEmpty(value.cursor, "cursor") };
-    case "paused":
-    case "blocked":
-      exactKeys(value, ["state", "reasonCode"], `${value.state} state`);
-      return { state: value.state, reasonCode: nonEmpty(value.reasonCode, "reasonCode") };
-    case "reset-required":
-      exactKeys(value, ["state", "resetId", "snapshotDescriptorId"], "reset-required state");
-      return {
-        state: value.state,
-        resetId: nonEmpty(value.resetId, "resetId"),
-        snapshotDescriptorId: nonEmpty(value.snapshotDescriptorId, "snapshotDescriptorId"),
-      };
-    case "revoked":
-      exactKeys(value, ["state", "localMaterialPolicy"], "revoked state");
-      return { state: value.state, localMaterialPolicy: nonEmpty(value.localMaterialPolicy, "localMaterialPolicy") };
-    default:
-      throw new Error(`realtime inventory: unsupported scope state ${value.state}`);
-  }
-}
-
-export function parseRealtimeInventory(value: unknown): RealtimeInventory {
-  if (!isRecord(value)) throw new Error("realtime inventory: response is not an object");
-  exactKeys(value, ["scopes"], "response");
-  if (!Array.isArray(value.scopes)) throw new Error("realtime inventory: scopes is not an array");
-  const scopeHandles = new Set<string>();
-  const scopes = value.scopes.map((entry): RealtimeInventoryGrant => {
-    if (!isRecord(entry)) throw new Error("realtime inventory: scope grant is not an object");
-    const { scopeUid, scopeHandle, scopeRevision, ...state } = entry;
-    const parsedState = parseState(state);
-    const grant = {
-      scopeUid: nonEmpty(scopeUid, "scopeUid"),
-      scopeHandle: nonEmpty(scopeHandle, "scopeHandle"),
-      scopeRevision: nonEmpty(scopeRevision, "scopeRevision"),
-      ...parsedState,
-    } as RealtimeInventoryGrant;
-    if (scopeHandles.has(grant.scopeHandle)) {
-      throw new Error("realtime inventory: duplicate scopeHandle");
-    }
-    scopeHandles.add(grant.scopeHandle);
-    return grant;
-  });
-  return { scopes };
-}
-
-function inventoryCacheKey(request: RealtimeInventoryRequest): string {
-  const capability = request.capabilityVector;
-  return JSON.stringify([
-    request.bearer,
-    request.deviceId,
-    request.configurationFingerprint,
-    request.scopeFingerprint,
-    capability.hqCloud,
-    capability.hqDesktop,
-    capability.protocol,
-    capability.journal,
-    capability.durableApply,
-  ]);
-}
-
-function cacheAgeForInventory(inventory: RealtimeInventory, maximum: number): number {
-  return inventory.scopes.reduce((age, grant) => {
-    if (
-      grant.state === "qualifying" ||
-      grant.state === "frozen" ||
-      grant.state === "seeding" ||
-      grant.state === "restoring"
-    ) return Math.min(age, grant.retryAfterMs);
-    if (grant.state === "legacy" || grant.state === "v2-ready") return age;
-    return 0;
-  }, maximum);
-}
-
-/**
- * Strict client for the authenticated inventory endpoint. The cache is keyed
- * by bearer, device, capability/configuration, and the scope selection. A
- * positive inventory record is only an optimization: callers must still mint
- * a new lease before I/O, where the server strongly rechecks all authority.
- */
-export class RealtimeRolloutClient {
-  private readonly apiUrl: string;
-  private readonly fetchImpl: FetchLike;
-  private readonly now: () => number;
-  private readonly maxCacheAgeMs: number;
-  private readonly authorizationTimeoutMs: number;
-  private readonly cache = new Map<string, CachedInventory>();
-
-  constructor(options: RealtimeRolloutClientOptions) {
-    if (!options.apiUrl.trim()) throw new Error("realtime inventory: apiUrl is required");
-    this.apiUrl = options.apiUrl.replace(/\/+$/, "");
-    this.fetchImpl = options.fetchImpl ?? ((input, init) => (globalThis.fetch as unknown as FetchLike)(input, init));
-    this.now = options.now ?? Date.now;
-    this.maxCacheAgeMs = options.maxCacheAgeMs ?? MAX_REALTIME_ROLLOUT_CACHE_MS;
-    if (!Number.isSafeInteger(this.maxCacheAgeMs) || this.maxCacheAgeMs < 0 || this.maxCacheAgeMs > MAX_REALTIME_ROLLOUT_CACHE_MS) {
-      throw new Error(`realtime inventory: maxCacheAgeMs must be within 0-${MAX_REALTIME_ROLLOUT_CACHE_MS}`);
-    }
-    this.authorizationTimeoutMs = options.authorizationTimeoutMs ?? DEFAULT_REALTIME_AUTHORIZATION_TIMEOUT_MS;
-    if (!Number.isSafeInteger(this.authorizationTimeoutMs) || this.authorizationTimeoutMs <= 0) {
-      throw new Error("realtime inventory: authorizationTimeoutMs must be a positive integer");
-    }
-  }
-
-  invalidate(): void {
-    this.cache.clear();
-  }
-
-  async inventory(request: RealtimeInventoryRequest): Promise<RealtimeInventory> {
-    const now = this.now();
-    for (const [key, entry] of this.cache) {
-      if (entry.expiresAt <= now) this.cache.delete(key);
-    }
-    const cacheKey = inventoryCacheKey(request);
-    const cached = this.cache.get(cacheKey);
-    if (cached && now < cached.expiresAt) return cached.value;
-
-    const controller = new AbortController();
-    const timeout = setTimeout(() => controller.abort(), this.authorizationTimeoutMs);
-    let response: Awaited<ReturnType<FetchLike>>;
-    try {
-      response = await this.fetchImpl(`${this.apiUrl}/v2/sync/scopes`, {
-        method: "GET",
-        headers: {
-          Authorization: `Bearer ${request.bearer}`,
-          Accept: "application/json",
-          "X-HQ-Sync-Contract": String(REALTIME_SYNC_CONTRACT_VERSION),
-          "X-HQ-Device-ID": request.deviceId,
-          "X-HQ-Cloud-Version": request.capabilityVector.hqCloud,
-          "X-HQ-Desktop-Version": request.capabilityVector.hqDesktop,
-          "X-HQ-Sync-Journal": String(request.capabilityVector.journal),
-          "X-HQ-Sync-Durable-Apply": String(request.capabilityVector.durableApply),
-        },
-        signal: controller.signal,
-      });
-    } catch (error) {
-      throw new Error(`realtime inventory: GET /v2/sync/scopes failed: ${error instanceof Error ? error.message : String(error)}`);
-    } finally {
-      clearTimeout(timeout);
-    }
-    const text = await response.text().catch((error: unknown) => {
-      throw new Error(`realtime inventory: unable to read response: ${error instanceof Error ? error.message : String(error)}`);
-    });
-    if (!response.ok) throw new Error(`realtime inventory: GET /v2/sync/scopes failed (${response.status}): ${text.slice(0, 300)}`);
-    let parsed: unknown;
-    try {
-      parsed = JSON.parse(text);
-    } catch (error) {
-      throw new Error(`realtime inventory: response is not JSON: ${error instanceof Error ? error.message : String(error)}`);
-    }
-    const inventory = parseRealtimeInventory(parsed);
-    const cacheAgeMs = cacheAgeForInventory(inventory, this.maxCacheAgeMs);
-    if (cacheAgeMs > 0) this.cache.set(cacheKey, { value: inventory, expiresAt: this.now() + cacheAgeMs });
-    return inventory;
-  }
-}
-
-export async function resolveRealtimeBearer(source: AuthTokenSource): Promise<string> {
-  const bearer = typeof source === "function" ? await source() : source;
-  if (typeof bearer !== "string" || bearer.trim() === "") throw new Error("realtime authorization: access token is empty");
-  return bearer;
-}