@indigoai-us/hq-cloud 5.19.1 → 5.21.0

package/src/entity-resolver.test.ts

@@ -0,0 +1,315 @@
+/**
+ * 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 { clearContextCache } from "./context.js";
+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 /sts/vend  (canonical vault-service endpoint; was /entities/{uid}/sts
+    // in early drafts but that path doesn't actually exist server-side — the
+    // resolver now delegates to resolveEntityContext() which uses this route).
+    if (method === "POST" && url.endsWith("/sts/vend")) {
+      if (opts.stsStatus && opts.stsStatus >= 400) {
+        const body = opts.stsBody ?? { error: `STS error ${opts.stsStatus}` };
+        return json(body, opts.stsStatus);
+      }
+      // resolveEntityContext also re-fetches /entity/{uid} before vending, so
+      // the test mock above already handles that. Return creds + expiresAt;
+      // bucket/region come from the entity object + config respectively.
+      return json(opts.stsBody ?? {
+        credentials: STS_CREDS.credentials,
+        expiresAt: STS_CREDS.expiresAt,
+      });
+    }
+
+    return json({ error: `Unhandled: ${method} ${url}` }, 500);
+  });
+
+  vi.stubGlobal("fetch", fetchMock);
+  return fetchMock;
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+beforeEach(() => {
+  vi.restoreAllMocks();
+  // resolveEntity delegates to resolveEntityContext (context.ts), which
+  // caches by UID. The cache must be cleared between tests, otherwise a
+  // 200 response from the success test sticks around and the subsequent
+  // 403/500 tests see a cached EntityContext and never call fetch.
+  clearContextCache();
+});
+
+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,180 @@
+/**
+ * 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)
+ * rather than JWT claims, which are fragile post-migration (see
+ * indigo-jwt-claims-fragile-post-migration). Delegates STS vending to the
+ * canonical `resolveEntityContext()` in context.ts so we use the actual
+ * vault-service endpoint (POST /sts/vend) rather than a made-up one.
+ */
+
+import {
+  VaultClient,
+  VaultClientError,
+  VaultPermissionDeniedError,
+} from "./vault-client.js";
+import type { MembershipRole } from "./vault-client.js";
+import type { EntityContext, VaultServiceConfig } from "./types.js";
+import { resolveEntityContext } from "./context.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) — throw EntityNotFoundError
+ *    with the list of available slugs if it doesn't match (better UX than
+ *    the raw 404 from /entity/by-slug/{slug}).
+ * 4. Delegate to resolveEntityContext(uid) → POST /sts/vend (the actual
+ *    vault-service endpoint).
+ */
+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 via the canonical context resolver.
+  // resolveEntityContext re-fetches the entity by UID (one extra hop) and
+  // calls POST /sts/vend (the actual endpoint) — re-using its caching +
+  // refresh logic is worth more than the redundant fetch.
+  try {
+    return await resolveEntityContext(match.entity.uid, opts.vaultConfig);
+  } 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,
+      );
+    }
+    // resolveEntityContext throws plain Error on STS HTTP failures
+    // (`STS /sts/vend failed: <status> <body>`). Extract the status code
+    // and surface the right typed error for the caller.
+    const msg = err instanceof Error ? err.message : String(err);
+    const statusMatch = /STS\s+\S+\s+failed:\s+(\d{3})\b/i.exec(msg);
+    const statusCode = statusMatch ? parseInt(statusMatch[1], 10) : 500;
+    if (statusCode === 403) {
+      throw new EntityPermissionError(opts.slug, msg);
+    }
+    throw new EntityResolutionError(
+      `STS vending failed for entity '${opts.slug}': ${msg}`,
+      statusCode,
+    );
+  }
+}
+
+// ---------------------------------------------------------------------------
+// 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,66 @@ 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";
+
+// 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";

package/src/schemas/signal-types.test.ts

@@ -0,0 +1,82 @@
+import { describe, it, expect } from "vitest";
+import {
+  SIGNAL_TYPES,
+  isSignalType,
+  assertSignalType,
+  InvalidSignalTypeError,
+} from "./signal-types.js";
+import type { SignalType } from "./signal-types.js";
+
+describe("SIGNAL_TYPES", () => {
+  it("contains the six canonical types", () => {
+    expect([...SIGNAL_TYPES]).toEqual([
+      "action_item",
+      "commitment",
+      "decision",
+      "key_point",
+      "risk",
+      "summary",
+    ]);
+  });
+
+  it("is frozen (readonly at runtime)", () => {
+    expect(Object.isFrozen(SIGNAL_TYPES)).toBe(true);
+  });
+});
+
+describe("isSignalType", () => {
+  it.each(SIGNAL_TYPES)("returns true for '%s'", (type) => {
+    expect(isSignalType(type)).toBe(true);
+  });
+
+  it("returns false for an invalid string", () => {
+    expect(isSignalType("ramble")).toBe(false);
+  });
+
+  it("returns false for non-string values", () => {
+    expect(isSignalType(42)).toBe(false);
+    expect(isSignalType(null)).toBe(false);
+    expect(isSignalType(undefined)).toBe(false);
+  });
+});
+
+describe("assertSignalType", () => {
+  it.each(SIGNAL_TYPES)("does not throw for '%s'", (type) => {
+    expect(() => assertSignalType(type)).not.toThrow();
+  });
+
+  it("throws InvalidSignalTypeError for invalid value", () => {
+    expect(() => assertSignalType("ramble")).toThrow(InvalidSignalTypeError);
+  });
+
+  it("error message contains the offending value", () => {
+    expect(() => assertSignalType("ramble")).toThrow("'ramble'");
+  });
+
+  it("error message lists all valid types", () => {
+    try {
+      assertSignalType("ramble");
+    } catch (err) {
+      const msg = (err as Error).message;
+      for (const type of SIGNAL_TYPES) {
+        expect(msg).toContain(type);
+      }
+    }
+  });
+
+  it("error message matches snapshot", () => {
+    expect(() => assertSignalType("ramble")).toThrowErrorMatchingInlineSnapshot(
+      `[InvalidSignalTypeError: Invalid signal type: 'ramble'. Valid types: action_item, commitment, decision, key_point, risk, summary]`,
+    );
+  });
+});
+
+describe("SignalType type", () => {
+  it("narrows correctly via type guard", () => {
+    const value: unknown = "action_item";
+    if (isSignalType(value)) {
+      const _type: SignalType = value;
+      expect(_type).toBe("action_item");
+    }
+  });
+});

package/src/schemas/signal-types.ts

@@ -0,0 +1,38 @@
+/**
+ * Signal type schema — single source of truth.
+ *
+ * Closed enum: the six canonical signal types.
+ * assertSignalType is the agent-mitigation lever — prevents LLMs
+ * from fabricating signal types.
+ */
+
+export const SIGNAL_TYPES = Object.freeze([
+  "action_item",
+  "commitment",
+  "decision",
+  "key_point",
+  "risk",
+  "summary",
+] as const);
+
+export type SignalType = (typeof SIGNAL_TYPES)[number];
+
+export class InvalidSignalTypeError extends Error {
+  override readonly name = "InvalidSignalTypeError";
+
+  constructor(value: unknown) {
+    super(
+      `Invalid signal type: '${String(value)}'. Valid types: ${SIGNAL_TYPES.join(", ")}`,
+    );
+  }
+}
+
+export function isSignalType(value: unknown): value is SignalType {
+  return typeof value === "string" && (SIGNAL_TYPES as readonly string[]).includes(value);
+}
+
+export function assertSignalType(value: unknown): asserts value is SignalType {
+  if (!isSignalType(value)) {
+    throw new InvalidSignalTypeError(value);
+  }
+}