@indigoai-us/hq-cloud 5.19.1 → 5.20.0

package/src/bin/sync-runner.ts

@@ -83,6 +83,7 @@ import { share as defaultShare } from "../cli/share.js";
 import type { ShareOptions, ShareResult } from "../cli/share.js";
 import type { ConflictStrategy } from "../cli/conflict.js";
 import type { UploadAuthor } from "../s3.js";
+import { collectAndSendTelemetry } from "../telemetry.js";
 
 /**
  * Sync direction for a run.
@@ -278,6 +279,15 @@ export interface RunnerDeps {
   sync?: (options: SyncOptions) => Promise<SyncResult>;
   /** Share function (push phase). Defaults to `cli/share.share`. */
   share?: (options: ShareOptions) => Promise<ShareResult>;
+  /**
+   * Telemetry collector — runs just before the `all-complete` emit. Default
+   * implementation calls `collectAndSendTelemetry` from `../telemetry.js`
+   * using the real VaultClient; tests that inject `createVaultClient` are
+   * implicitly opted out (the default skips when the client isn't a real
+   * `VaultClient`). Tests that want to assert telemetry behavior should pass
+   * an explicit stub here.
+   */
+  collectTelemetry?: () => Promise<void>;
 }
 
 // ---------------------------------------------------------------------------
@@ -445,6 +455,55 @@ function parseArgs(argv: string[]): ParsedArgs | { error: string } {
   return { companies, company, onConflict, hqRoot, direction, watch, pollRemoteMs };
 }
 
+// ---------------------------------------------------------------------------
+// Telemetry default — closes over the runner's vault client. Skipped when
+// the caller injected a `createVaultClient` stub, because we have no
+// guarantee the stub implements `getTelemetryOptIn` / `postUsage`. The real
+// `VaultClient` from `../vault-client.js` always does. All errors are
+// swallowed — telemetry must never abort or delay sync.
+// ---------------------------------------------------------------------------
+
+async function defaultCollectTelemetry(
+  client: VaultClientSurface,
+  clientIsStub: boolean,
+): Promise<void> {
+  if (clientIsStub) return;
+  try {
+    // machineId: prefer ~/.hq/menubar.json (set by the menubar app on first
+    // launch). When absent — e.g. fresh CLI-only install — fall back to a
+    // value that makes the row identifiable as "unattributed" rather than
+    // crashing or spoofing another machine's id.
+    const menubarPath = path.join(os.homedir(), ".hq", "menubar.json");
+    let machineId = "unknown";
+    try {
+      const raw = await fs.promises.readFile(menubarPath, "utf-8");
+      const parsed = JSON.parse(raw) as { machineId?: unknown };
+      if (typeof parsed.machineId === "string" && parsed.machineId.length > 0) {
+        machineId = parsed.machineId;
+      }
+    } catch {
+      // No menubar.json — proceed with "unknown".
+    }
+
+    // installerVersion: callers (the Tauri menubar) set this when spawning
+    // the runner so the historical `installerVersion` dimension on
+    // CloudWatch keeps reporting the menubar version, not the runner's
+    // package version. CLI callers can leave it unset.
+    const installerVersion = process.env.HQ_INSTALLER_VERSION ?? "hq-cloud";
+
+    await collectAndSendTelemetry({
+      // The runtime guarantee here is that `clientIsStub === false` means
+      // `client` came from `new VaultClient(vaultConfig)` (see runRunner),
+      // which structurally satisfies `TelemetryClientSurface`.
+      client: client as unknown as Parameters<typeof collectAndSendTelemetry>[0]["client"],
+      machineId,
+      installerVersion,
+    });
+  } catch {
+    // Fire-and-forget; nothing escapes the boundary.
+  }
+}
+
 // ---------------------------------------------------------------------------
 // runRunner — testable entrypoint
 // ---------------------------------------------------------------------------
@@ -922,6 +981,20 @@ export async function runRunner(
     });
   }
 
+  // Fire telemetry collector before the all-complete emit so the cursor at
+  // `~/.hq/telemetry-cursor.json` is consistent with what the menubar sees.
+  // Awaited fully — fire-and-forget would lose in-flight POSTs at process
+  // exit, and the previous 10s race was wrong: a first-run user with
+  // backlog (e.g. 60K Claude session events) takes well over 10s legitimately,
+  // and the race silently dropped the entire batch when it fired. Errors
+  // are swallowed inside `defaultCollectTelemetry`; per-request timeouts
+  // come from `VaultClient`'s retry loop (3 attempts × exponential backoff),
+  // which naturally bounds the outer wait.
+  const telemetryFn =
+    deps.collectTelemetry ??
+    (() => defaultCollectTelemetry(client, deps.createVaultClient !== undefined));
+  await telemetryFn().catch(() => undefined);
+
   emit({
     type: "all-complete",
     companiesAttempted: plan.length,

package/src/entity-resolver.test.ts

@@ -0,0 +1,307 @@
+/**
+ * Unit tests for entity-resolver.ts — slug → EntityContext resolution.
+ *
+ * Mocks globalThis.fetch to simulate vault-service responses for:
+ *   GET  /membership/me          → list memberships
+ *   GET  /entity/{uid}           → entity info (slug, bucketName)
+ *   POST /entities/{uid}/sts     → STS credentials
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import {
+  resolveEntity,
+  listAvailableEntities,
+  EntityNotFoundError,
+  EntityPermissionError,
+  EntityResolutionError,
+} from "./entity-resolver.js";
+import type { VaultServiceConfig } from "./types.js";
+
+// ---------------------------------------------------------------------------
+// Test fixtures
+// ---------------------------------------------------------------------------
+
+const VAULT_CONFIG: VaultServiceConfig = {
+  apiUrl: "https://vault.test",
+  authToken: "test-jwt",
+  region: "us-east-1",
+};
+
+const ENTITIES = {
+  indigo: {
+    uid: "cmp_indigo_001",
+    slug: "indigo",
+    type: "company",
+    name: "Indigo",
+    bucketName: "hq-vault-indigo",
+    status: "active",
+  },
+  personal: {
+    uid: "cmp_personal_001",
+    slug: "personal",
+    type: "person",
+    name: "Stefan",
+    bucketName: "hq-vault-personal",
+    status: "active",
+  },
+};
+
+const STS_CREDS = {
+  credentials: {
+    accessKeyId: "ASIAMOCK000000000001",
+    secretAccessKey: "mockSecret",
+    sessionToken: "mockSession",
+  },
+  expiresAt: new Date(Date.now() + 3600_000).toISOString(),
+  bucketName: "hq-vault-indigo",
+  region: "us-east-1",
+};
+
+// ---------------------------------------------------------------------------
+// Mock helpers
+// ---------------------------------------------------------------------------
+
+function json(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "Content-Type": "application/json" },
+  });
+}
+
+interface MockOptions {
+  memberships?: Array<{ companyUid: string; role: string }>;
+  entities?: Record<string, typeof ENTITIES.indigo>;
+  stsStatus?: number;
+  stsBody?: unknown;
+  entityStatus?: number;
+}
+
+function setupFetchMock(opts: MockOptions = {}) {
+  const memberships = opts.memberships ?? [
+    { companyUid: "cmp_indigo_001", role: "owner" },
+    { companyUid: "cmp_personal_001", role: "owner" },
+  ];
+
+  const entities = opts.entities ?? {
+    cmp_indigo_001: ENTITIES.indigo,
+    cmp_personal_001: ENTITIES.personal,
+  };
+
+  const fetchMock = vi.fn(async (input: string | URL | Request, init?: RequestInit) => {
+    const url = typeof input === "string" ? input : input.toString();
+    const method = (init?.method ?? "GET").toUpperCase();
+
+    // GET /membership/me
+    if (method === "GET" && url.endsWith("/membership/me")) {
+      return json({
+        memberships: memberships.map((m) => ({
+          membershipKey: `mbr_${m.companyUid}`,
+          personUid: "prs_test_001",
+          companyUid: m.companyUid,
+          role: m.role,
+          status: "active",
+          invitedBy: "system",
+          invitedAt: "2026-01-01T00:00:00Z",
+          createdAt: "2026-01-01T00:00:00Z",
+          updatedAt: "2026-01-01T00:00:00Z",
+        })),
+      });
+    }
+
+    // GET /entity/{uid}
+    const entityGetMatch = /\/entity\/([^/?]+)$/.exec(url);
+    if (method === "GET" && entityGetMatch) {
+      const uid = decodeURIComponent(entityGetMatch[1]);
+      const entity = entities[uid as keyof typeof entities];
+      if (!entity || opts.entityStatus === 404) {
+        return json({ error: "Not found" }, opts.entityStatus ?? 404);
+      }
+      return json({ entity });
+    }
+
+    // POST /entities/{uid}/sts
+    const stsMatch = /\/entities\/([^/]+)\/sts/.exec(url);
+    if (method === "POST" && stsMatch) {
+      const uid = decodeURIComponent(stsMatch[1]);
+      if (opts.stsStatus && opts.stsStatus >= 400) {
+        const body = opts.stsBody ?? { error: `STS error ${opts.stsStatus}` };
+        return json(body, opts.stsStatus);
+      }
+      const entity = entities[uid as keyof typeof entities];
+      return json(opts.stsBody ?? {
+        ...STS_CREDS,
+        bucketName: entity?.bucketName ?? STS_CREDS.bucketName,
+      });
+    }
+
+    return json({ error: `Unhandled: ${method} ${url}` }, 500);
+  });
+
+  vi.stubGlobal("fetch", fetchMock);
+  return fetchMock;
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+beforeEach(() => {
+  vi.restoreAllMocks();
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe("resolveEntity", () => {
+  it("resolves entity by slug (happy path)", async () => {
+    setupFetchMock();
+
+    const ctx = await resolveEntity({ slug: "indigo", vaultConfig: VAULT_CONFIG });
+
+    expect(ctx.uid).toBe("cmp_indigo_001");
+    expect(ctx.slug).toBe("indigo");
+    expect(ctx.bucketName).toBe("hq-vault-indigo");
+    expect(ctx.region).toBe("us-east-1");
+    expect(ctx.credentials.accessKeyId).toBe("ASIAMOCK000000000001");
+    expect(ctx.credentials.secretAccessKey).toBe("mockSecret");
+    expect(ctx.credentials.sessionToken).toBe("mockSession");
+    expect(ctx.expiresAt).toBeTruthy();
+  });
+
+  it("resolves 'personal' slug without special-casing", async () => {
+    setupFetchMock();
+
+    const ctx = await resolveEntity({ slug: "personal", vaultConfig: VAULT_CONFIG });
+
+    expect(ctx.uid).toBe("cmp_personal_001");
+    expect(ctx.slug).toBe("personal");
+    expect(ctx.bucketName).toBe("hq-vault-personal");
+  });
+
+  it("throws EntityNotFoundError when slug not found", async () => {
+    setupFetchMock();
+
+    await expect(
+      resolveEntity({ slug: "unknown", vaultConfig: VAULT_CONFIG }),
+    ).rejects.toThrow(EntityNotFoundError);
+
+    try {
+      await resolveEntity({ slug: "unknown", vaultConfig: VAULT_CONFIG });
+    } catch (err) {
+      expect(err).toBeInstanceOf(EntityNotFoundError);
+      const e = err as EntityNotFoundError;
+      expect(e.message).toContain("unknown");
+      expect(e.message).toContain("indigo");
+      expect(e.message).toContain("personal");
+    }
+  });
+
+  it("throws EntityNotFoundError with (none) when user has no memberships", async () => {
+    setupFetchMock({ memberships: [] });
+
+    await expect(
+      resolveEntity({ slug: "indigo", vaultConfig: VAULT_CONFIG }),
+    ).rejects.toThrow(EntityNotFoundError);
+
+    try {
+      await resolveEntity({ slug: "indigo", vaultConfig: VAULT_CONFIG });
+    } catch (err) {
+      expect((err as Error).message).toContain("(none)");
+    }
+  });
+
+  it("throws EntityPermissionError on 403 from STS", async () => {
+    setupFetchMock({ stsStatus: 403, stsBody: { error: "Permission denied" } });
+
+    await expect(
+      resolveEntity({ slug: "indigo", vaultConfig: VAULT_CONFIG }),
+    ).rejects.toThrow(EntityPermissionError);
+  });
+
+  it("throws EntityResolutionError on 500 from STS", async () => {
+    setupFetchMock({ stsStatus: 500, stsBody: { error: "Internal error" } });
+
+    let caught: unknown;
+    try {
+      await resolveEntity({ slug: "indigo", vaultConfig: VAULT_CONFIG });
+    } catch (err) {
+      caught = err;
+    }
+
+    expect(caught).toBeInstanceOf(EntityResolutionError);
+    expect((caught as EntityResolutionError).statusCode).toBe(500);
+  }, 15_000);
+
+  it("rejects slug case-mismatch (case-sensitive)", async () => {
+    setupFetchMock();
+
+    await expect(
+      resolveEntity({ slug: "Indigo", vaultConfig: VAULT_CONFIG }),
+    ).rejects.toThrow(EntityNotFoundError);
+
+    try {
+      await resolveEntity({ slug: "Indigo", vaultConfig: VAULT_CONFIG });
+    } catch (err) {
+      expect((err as Error).message).toContain("Indigo");
+      expect((err as Error).message).toContain("indigo");
+    }
+  });
+
+  it("throws EntityResolutionError when entity has no bucket", async () => {
+    setupFetchMock({
+      entities: {
+        cmp_indigo_001: { ...ENTITIES.indigo, bucketName: undefined as unknown as string },
+        cmp_personal_001: ENTITIES.personal,
+      },
+    });
+
+    await expect(
+      resolveEntity({ slug: "indigo", vaultConfig: VAULT_CONFIG }),
+    ).rejects.toThrow(EntityResolutionError);
+
+    try {
+      await resolveEntity({ slug: "indigo", vaultConfig: VAULT_CONFIG });
+    } catch (err) {
+      expect((err as Error).message).toContain("no bucket provisioned");
+    }
+  });
+});
+
+describe("listAvailableEntities", () => {
+  it("returns all available entities with slug, uid, and role", async () => {
+    setupFetchMock();
+
+    const entities = await listAvailableEntities({ vaultConfig: VAULT_CONFIG });
+
+    expect(entities).toHaveLength(2);
+    expect(entities).toEqual(
+      expect.arrayContaining([
+        { slug: "indigo", uid: "cmp_indigo_001", role: "owner" },
+        { slug: "personal", uid: "cmp_personal_001", role: "owner" },
+      ]),
+    );
+  });
+
+  it("returns empty array when user has no memberships", async () => {
+    setupFetchMock({ memberships: [] });
+
+    const entities = await listAvailableEntities({ vaultConfig: VAULT_CONFIG });
+
+    expect(entities).toEqual([]);
+  });
+
+  it("preserves role from membership", async () => {
+    setupFetchMock({
+      memberships: [
+        { companyUid: "cmp_indigo_001", role: "member" },
+      ],
+      entities: { cmp_indigo_001: ENTITIES.indigo },
+    });
+
+    const entities = await listAvailableEntities({ vaultConfig: VAULT_CONFIG });
+
+    expect(entities).toHaveLength(1);
+    expect(entities[0].role).toBe("member");
+  });
+});

package/src/entity-resolver.ts

@@ -0,0 +1,173 @@
+/**
+ * Entity resolver — maps a human-readable slug to an EntityContext with
+ * STS-vended credentials.
+ *
+ * Uses the membership-based discovery path (GET /membership/me → entity lookup
+ * → POST /entities/{uid}/sts) rather than JWT claims, which are fragile
+ * post-migration (see indigo-jwt-claims-fragile-post-migration).
+ */
+
+import {
+  VaultClient,
+  VaultClientError,
+  VaultPermissionDeniedError,
+} from "./vault-client.js";
+import type { MembershipRole, EntityInfo } from "./vault-client.js";
+import type { EntityContext, VaultServiceConfig } from "./types.js";
+
+// ---------------------------------------------------------------------------
+// Error classes
+// ---------------------------------------------------------------------------
+
+export class EntityNotFoundError extends Error {
+  constructor(slug: string, availableSlugs: string[]) {
+    const available = availableSlugs.length > 0
+      ? availableSlugs.join(", ")
+      : "(none)";
+    super(`Entity '${slug}' not found. Available: ${available}`);
+    this.name = "EntityNotFoundError";
+  }
+}
+
+export class EntityPermissionError extends Error {
+  constructor(slug: string, message?: string) {
+    super(message ?? `Permission denied for entity '${slug}'`);
+    this.name = "EntityPermissionError";
+  }
+}
+
+export class EntityResolutionError extends Error {
+  constructor(
+    message: string,
+    public readonly statusCode: number,
+    public readonly body?: string,
+  ) {
+    super(message);
+    this.name = "EntityResolutionError";
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+export interface AvailableEntity {
+  slug: string;
+  uid: string;
+  role: MembershipRole;
+}
+
+// ---------------------------------------------------------------------------
+// resolveEntity
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve a human-readable entity slug to a fully hydrated EntityContext
+ * with STS-scoped credentials ready for S3 operations.
+ *
+ * Flow:
+ * 1. GET /membership/me → list user's active memberships (companyUids)
+ * 2. GET /entity/{uid} for each → resolve slug + bucketName
+ * 3. Match the requested slug (case-sensitive)
+ * 4. POST /entities/{uid}/sts → vend STS credentials
+ */
+export async function resolveEntity(opts: {
+  slug: string;
+  vaultConfig: VaultServiceConfig;
+}): Promise<EntityContext> {
+  const client = new VaultClient(opts.vaultConfig);
+
+  // Step 1: List memberships
+  const memberships = await client.listMyMemberships();
+
+  if (memberships.length === 0) {
+    throw new EntityNotFoundError(opts.slug, []);
+  }
+
+  // Step 2: Resolve entity info for each membership (parallel)
+  const resolved = await Promise.all(
+    memberships.map(async (m) => {
+      const entity = await client.entity.get(m.companyUid);
+      return { entity, role: m.role };
+    }),
+  );
+
+  // Step 3: Find matching slug (case-sensitive)
+  const match = resolved.find(({ entity }) => entity.slug === opts.slug);
+
+  if (!match) {
+    const availableSlugs = resolved.map(({ entity }) => entity.slug);
+    throw new EntityNotFoundError(opts.slug, availableSlugs);
+  }
+
+  if (!match.entity.bucketName) {
+    throw new EntityResolutionError(
+      `Entity '${opts.slug}' (${match.entity.uid}) has no bucket provisioned`,
+      500,
+    );
+  }
+
+  // Step 4: Vend STS credentials
+  let stsResult;
+  try {
+    stsResult = await client.sts.vendForEntity(match.entity.uid);
+  } catch (err) {
+    if (err instanceof VaultPermissionDeniedError) {
+      throw new EntityPermissionError(opts.slug, err.message);
+    }
+    if (err instanceof VaultClientError) {
+      throw new EntityResolutionError(
+        `STS vending failed for entity '${opts.slug}': ${err.message}`,
+        err.statusCode,
+        err.body,
+      );
+    }
+    throw err;
+  }
+
+  return {
+    uid: match.entity.uid,
+    slug: match.entity.slug,
+    bucketName: stsResult.bucketName,
+    region: stsResult.region,
+    credentials: {
+      accessKeyId: stsResult.credentials.accessKeyId,
+      secretAccessKey: stsResult.credentials.secretAccessKey,
+      sessionToken: stsResult.credentials.sessionToken,
+    },
+    expiresAt: stsResult.expiresAt,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// listAvailableEntities
+// ---------------------------------------------------------------------------
+
+/**
+ * List all entities the caller has access to, with slug, UID, and role.
+ * Used by `hq sources entities` / `hq signals entities` for discovery.
+ */
+export async function listAvailableEntities(opts: {
+  vaultConfig: VaultServiceConfig;
+}): Promise<AvailableEntity[]> {
+  const client = new VaultClient(opts.vaultConfig);
+
+  const memberships = await client.listMyMemberships();
+
+  if (memberships.length === 0) {
+    return [];
+  }
+
+  const resolved = await Promise.all(
+    memberships.map(async (m) => {
+      const entity = await client.entity.get(m.companyUid);
+      return {
+        slug: entity.slug,
+        uid: entity.uid,
+        role: m.role,
+      };
+    }),
+  );
+
+  return resolved;
+}

package/src/index.ts

@@ -77,8 +77,21 @@ export type {
   CreateEntityInput,
   CreateEntityResult,
   PendingInviteByEmail,
+  TelemetryOptInResponse,
+  UsageBatch,
+  UsageIngestResult,
 } from "./vault-client.js";
 
+// Usage telemetry collector (`/v1/usage`). Re-exported so wrappers other than
+// `hq-sync-runner` (mobile, custom CLIs) can run the collector on their own
+// schedule without re-implementing the cursor + sanitizer.
+export { collectAndSendTelemetry, sanitizeRow } from "./telemetry.js";
+export type {
+  CollectTelemetryOptions,
+  CollectTelemetryResult,
+  TelemetryClientSurface,
+} from "./telemetry.js";
+
 // STS child vending (VLT-8)
 export type {
   TaskAction,
@@ -127,3 +140,69 @@ export {
   HEADER_CLIENT_VERSION,
   HEADER_HQ_CORE_VERSION,
 } from "./client-info.js";
+
+// Source-channel + signal-type schemas (SoT)
+export {
+  SOURCE_CHANNELS,
+  isSourceChannel,
+  assertSourceChannel,
+  InvalidSourceChannelError,
+} from "./schemas/source-channels.js";
+export type { SourceChannel } from "./schemas/source-channels.js";
+
+export {
+  SIGNAL_TYPES,
+  isSignalType,
+  assertSignalType,
+  InvalidSignalTypeError,
+} from "./schemas/signal-types.js";
+export type { SignalType } from "./schemas/signal-types.js";
+
+// Entity resolver (sources/signals slug → EntityContext)
+export {
+  resolveEntity,
+  listAvailableEntities,
+  EntityNotFoundError,
+  EntityPermissionError,
+  EntityResolutionError,
+} from "./entity-resolver.js";
+export type { AvailableEntity } from "./entity-resolver.js";
+
+// Entity STS vending type
+export type { EntityStsResult } from "./vault-client.js";
+
+// Sources read surface
+export { listSources } from "./sources/list.js";
+export { getSource, SourceNotFoundError } from "./sources/get.js";
+export type {
+  SourceSummary,
+  SourceDocument,
+  ListSourcesOptions,
+  ListSourcesResult,
+  GetSourceOptions,
+} from "./sources/types.js";
+
+// Test-only S3 factory hook for sources (consumed by hq-cli tests).
+// Underscore prefix signals "not for production use".
+export {
+  _setSourcesS3Factory,
+  _resetSourcesS3Factory,
+} from "./sources/internals.js";
+
+// Signals read surface
+export { listSignals } from "./signals/list.js";
+export { getSignal, SignalNotFoundError } from "./signals/get.js";
+export type {
+  SignalSummary,
+  SignalDocument,
+  ListSignalsOptions,
+  ListSignalsResult,
+  GetSignalOptions,
+} from "./signals/types.js";
+
+// Test-only S3 factory hook for signals (consumed by hq-cli tests).
+// Underscore prefix signals "not for production use".
+export {
+  _setSignalsS3Factory,
+  _resetSignalsS3Factory,
+} from "./signals/internals.js";