@indigoai-us/hq-cloud 5.21.0 → 5.23.0

package/src/sources/get.test.ts

@@ -70,7 +70,7 @@ afterEach(() => _resetSourcesS3Factory());
 
 describe("getSource", () => {
   it("happy path: parses frontmatter and body", async () => {
-    installStub({ "sources/meeting/abc.md": MEETING_MD });
+    installStub({ "sources/meetings/abc.md": MEETING_MD });
 
     const doc = await getSource({
       entity: ENTITY,
@@ -78,7 +78,7 @@ describe("getSource", () => {
       sourceId: "abc",
     });
 
-    expect(doc.key).toBe("sources/meeting/abc.md");
+    expect(doc.key).toBe("sources/meetings/abc.md");
     expect(doc.frontmatter).toEqual({
       source_id: "abc",
       source_type: "meeting",
@@ -98,13 +98,13 @@ describe("getSource", () => {
 
     await expect(
       getSource({ entity: ENTITY, channel: "meeting", sourceId: "missing" }),
-    ).rejects.toThrow(/sources\/meeting\/missing\.md/);
+    ).rejects.toThrow(/sources\/meetings\/missing\.md/);
   });
 
   it("includeRaw:true fetches the .raw.json sibling", async () => {
     installStub({
-      "sources/meeting/abc.md": MEETING_MD,
-      "sources/meeting/abc.raw.json": JSON.stringify(RAW_PAYLOAD),
+      "sources/meetings/abc.md": MEETING_MD,
+      "sources/meetings/abc.raw.json": JSON.stringify(RAW_PAYLOAD),
     });
 
     const doc = await getSource({
@@ -118,7 +118,7 @@ describe("getSource", () => {
   });
 
   it("includeRaw:true tolerates missing .raw.json (raw stays undefined)", async () => {
-    installStub({ "sources/meeting/abc.md": MEETING_MD });
+    installStub({ "sources/meetings/abc.md": MEETING_MD });
 
     const doc = await getSource({
       entity: ENTITY,
@@ -152,7 +152,7 @@ describe("getSource", () => {
   });
 
   it("returns frontmatter:null for malformed (no frontmatter block) documents", async () => {
-    installStub({ "sources/meeting/plain.md": "Just a body, no frontmatter." });
+    installStub({ "sources/meetings/plain.md": "Just a body, no frontmatter." });
 
     const doc = await getSource({
       entity: ENTITY,

package/src/sources/get.ts

@@ -4,7 +4,7 @@
  */
 
 import { GetObjectCommand } from "@aws-sdk/client-s3";
-import { assertSourceChannel } from "../schemas/source-channels.js";
+import { assertSourceChannel, sourcePathSegment } from "../schemas/source-channels.js";
 import { getS3Client, streamToString } from "./internals.js";
 import { parseMarkdown } from "./parse.js";
 import type { GetSourceOptions, SourceDocument } from "./types.js";
@@ -28,7 +28,10 @@ export async function getSource(opts: GetSourceOptions): Promise<SourceDocument>
   assertSourceChannel(opts.channel);
 
   const client = getS3Client(opts.entity);
-  const key = `sources/${opts.channel}/${opts.sourceId}.md`;
+  // sources-pipeline writes "meeting" channel to sources/meetings/...; other
+  // channels pass through. See schemas/source-channels.ts:sourcePathSegment.
+  const segment = sourcePathSegment(opts.channel);
+  const key = `sources/${segment}/${opts.sourceId}.md`;
 
   let body: string;
   try {
@@ -55,7 +58,7 @@ export async function getSource(opts: GetSourceOptions): Promise<SourceDocument>
   };
 
   if (opts.includeRaw) {
-    const rawKey = `sources/${opts.channel}/${opts.sourceId}.raw.json`;
+    const rawKey = `sources/${segment}/${opts.sourceId}.raw.json`;
     try {
       const rawResponse = await client.send(
         new GetObjectCommand({

package/src/sources/list.test.ts

@@ -128,12 +128,12 @@ describe("listSources", () => {
   it("happy path: lists one source and skips its .raw.json sibling", async () => {
     installStub([
       {
-        key: "sources/meeting/abc.md",
+        key: "sources/meetings/abc.md",
         content: MEETING_MD,
         lastModified: new Date("2026-03-15T14:00:00Z"),
       },
       {
-        key: "sources/meeting/abc.raw.json",
+        key: "sources/meetings/abc.raw.json",
         content: '{"raw": true}',
         lastModified: new Date("2026-03-15T14:00:00Z"),
       },
@@ -144,7 +144,7 @@ describe("listSources", () => {
     expect(result.entries).toHaveLength(1);
     expect(result.entries[0].sourceId).toBe("abc");
     expect(result.entries[0].channel).toBe("meeting");
-    expect(result.entries[0].key).toBe("sources/meeting/abc.md");
+    expect(result.entries[0].key).toBe("sources/meetings/abc.md");
     expect(result.entries[0].size).toBeGreaterThan(0);
     expect(result.entries[0].frontmatter).toBeUndefined();
     expect(result.nextToken).toBeUndefined();
@@ -152,7 +152,7 @@ describe("listSources", () => {
 
   it("pagination: returns nextToken and accepts it on the next call", async () => {
     const objects: StoredObject[] = Array.from({ length: 5 }, (_, i) => ({
-      key: `sources/meeting/m${i}.md`,
+      key: `sources/meetings/m${i}.md`,
       content: MEETING_MD,
       lastModified: new Date("2026-03-15T14:00:00Z"),
     }));
@@ -189,7 +189,7 @@ describe("listSources", () => {
   it("includeFrontmatter:true fetches each object and parses YAML", async () => {
     const observed = installStub([
       {
-        key: "sources/meeting/abc.md",
+        key: "sources/meetings/abc.md",
         content: MEETING_MD,
         lastModified: new Date("2026-03-15T14:00:00Z"),
       },
@@ -215,7 +215,7 @@ describe("listSources", () => {
   it("includeFrontmatter:false (default) does not perform GETs", async () => {
     const observed = installStub([
       {
-        key: "sources/meeting/abc.md",
+        key: "sources/meetings/abc.md",
         content: MEETING_MD,
         lastModified: new Date(),
       },

package/src/sources/list.ts

@@ -10,7 +10,7 @@ import {
   GetObjectCommand,
   ListObjectsV2Command,
 } from "@aws-sdk/client-s3";
-import { assertSourceChannel } from "../schemas/source-channels.js";
+import { assertSourceChannel, sourcePathSegment } from "../schemas/source-channels.js";
 import { getS3Client, streamToString } from "./internals.js";
 import { parseFrontmatter } from "./parse.js";
 import type {
@@ -44,7 +44,9 @@ export async function listSources(opts: ListSourcesOptions): Promise<ListSources
   assertSourceChannel(opts.channel);
 
   const client = getS3Client(opts.entity);
-  const prefix = `sources/${opts.channel}/`;
+  // Use the canonical path segment from the schema; channel "meeting" maps
+  // to the plural "meetings/" prefix the sources-pipeline writes to.
+  const prefix = `sources/${sourcePathSegment(opts.channel)}/`;
 
   const response = await client.send(
     new ListObjectsV2Command({

package/src/types.ts

@@ -34,12 +34,60 @@ export interface JournalEntry {
    * against `syncedAt`.
    */
   remoteEtag?: string;
+  /**
+   * Tombstone marker (Journal v2, US-005). When set, this entry represents
+   * a file that was pruned by a scope shrink — either implicitly (next pull
+   * after the membership's effective scope narrowed) or explicitly (via
+   * `hq sync narrow --apply`). Tombstones are kept for `TOMBSTONE_TTL_MS`
+   * (30d) so subsequent pulls under the same shrunk scope don't re-flag
+   * the same paths as orphans, then garbage-collected.
+   */
+  removedAt?: string;
+  removedReason?: "scope_shrink" | "narrow_apply" | "manual";
+}
+
+/**
+ * Per-pull boundary record (Journal v2, US-005).
+ *
+ * Recorded at the end of every per-company sync leg so the next pull can
+ * detect "scope changed" against `prefixSet` and compute orphans
+ * deterministically. `pulls[]` is append-only; old records are not pruned
+ * (cheap, useful for incident forensics — one row per pull per company).
+ */
+export interface PullRecord {
+  /** ULID-shaped id (crockford base32, lexically sortable). */
+  pullId: string;
+  companyUid: string;
+  startedAt: string;
+  completedAt: string;
+  /** Effective sync-mode at pull start. */
+  syncMode: "all" | "shared" | "custom";
+  /**
+   * Coalesced prefixes used to drive ListObjectsV2 for this pull. Empty for
+   * v1-migrated records (no recorded scope; treated as full-bucket "all").
+   */
+  prefixSet: string[];
+  scopeChangeDetected: boolean;
+  orphansRemoved: number;
+  orphansBlocked: number;
 }
 
 export interface SyncJournal {
-  version: "1";
+  /**
+   * Schema version. `"1"` is the pre-US-005 shape (no `pulls`, no
+   * tombstone fields on entries). `"2"` adds per-pull records and
+   * tombstone markers; readers MUST tolerate either and migrate v1 → v2
+   * in place on the first v2 write.
+   */
+  version: "1" | "2";
   lastSync: string;
   files: Record<string, JournalEntry>;
+  /**
+   * Per-pull boundary records (v2 only). Always present on v2 journals.
+   * v1 journals do not carry this field — readers should treat absence as
+   * "no recorded history; treat last scope as 'all'/empty".
+   */
+  pulls?: PullRecord[];
 }
 
 export interface SyncStatus {

package/src/vault-client.test.ts

@@ -14,6 +14,8 @@ import {
   VaultClientError,
   pickCanonicalPersonEntity,
   type EntityInfo,
+  type ExplicitGrant,
+  type MembershipSyncConfig,
 } from "./vault-client.js";
 
 // ---------------------------------------------------------------------------
@@ -694,6 +696,263 @@ describe("VaultClient identity bootstrap", () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// Browse-vs-sync SDK methods (US-004)
+//
+// listMyExplicitGrants, getMembershipSyncConfig, setMembershipSyncConfig
+// wrap the US-002/US-003 hq-pro endpoints. Tests assert URL shape, payload
+// shape, error mapping (401/404/network), and the empty-grants fallback
+// that lets call sites treat "no grants" as a normal state.
+// ---------------------------------------------------------------------------
+
+describe("listMyExplicitGrants (US-004)", () => {
+  it("GETs /v1/files/grants with the company query param and returns grants[]", async () => {
+    const grant: ExplicitGrant = {
+      companyUid: "cmp_abc",
+      path: "shared/docs",
+      permission: "read",
+      source: "person",
+    };
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, {
+        grants: [grant],
+        computedAt: "2026-05-20T12:00:00.000Z",
+      }),
+    );
+
+    const grants = await client.listMyExplicitGrants("cmp_abc");
+
+    expect(grants).toEqual([grant]);
+
+    const [url, init] = fetchSpy.mock.calls[0] as [string, RequestInit];
+    expect(url).toBe(
+      "https://vault.test.example.com/v1/files/grants?company=cmp_abc",
+    );
+    expect(init.method).toBe("GET");
+    expect(init.body).toBeUndefined();
+  });
+
+  it("URL-encodes the companyUid query parameter", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, { grants: [], computedAt: "2026-05-20T12:00:00.000Z" }),
+    );
+
+    await client.listMyExplicitGrants("cmp/with spaces&weird=chars");
+
+    const [url] = fetchSpy.mock.calls[0] as [string];
+    expect(url).toBe(
+      "https://vault.test.example.com/v1/files/grants?company=cmp%2Fwith%20spaces%26weird%3Dchars",
+    );
+  });
+
+  it("returns [] when the server omits the grants key (empty graph)", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, { computedAt: "2026-05-20T12:00:00.000Z" }),
+    );
+
+    const grants = await client.listMyExplicitGrants("cmp_abc");
+    expect(grants).toEqual([]);
+  });
+
+  it("maps 401 to VaultAuthError", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(401, { error: "Missing or invalid authorization token" }),
+    );
+
+    await expect(client.listMyExplicitGrants("cmp_abc")).rejects.toThrow(
+      VaultAuthError,
+    );
+  });
+
+  it("maps 404 to VaultNotFoundError", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(404, { error: "Unknown route" }),
+    );
+
+    await expect(client.listMyExplicitGrants("cmp_abc")).rejects.toThrow(
+      VaultNotFoundError,
+    );
+  });
+
+  it("surfaces transport errors after exhausting retries", async () => {
+    fetchSpy.mockRejectedValue(new Error("ECONNREFUSED"));
+
+    await expect(client.listMyExplicitGrants("cmp_abc")).rejects.toThrow(
+      /ECONNREFUSED/,
+    );
+    // 1 initial + 3 retries = 4 attempts on a persistent network error.
+    expect(fetchSpy).toHaveBeenCalledTimes(4);
+  });
+});
+
+describe("getMembershipSyncConfig (US-004)", () => {
+  it("GETs /v1/memberships/{id}/sync-config and returns the row verbatim", async () => {
+    const row: MembershipSyncConfig = {
+      membershipId: "psn_1#cmp_abc",
+      syncMode: "custom",
+      customPaths: ["shared/docs", "personal/psn_1"],
+      isDefault: false,
+      updatedAt: "2026-05-20T12:00:00.000Z",
+      updatedBy: "psn_admin",
+    };
+    fetchSpy.mockResolvedValueOnce(jsonResponse(200, row));
+
+    const result = await client.getMembershipSyncConfig("psn_1#cmp_abc");
+
+    expect(result).toEqual(row);
+
+    const [url, init] = fetchSpy.mock.calls[0] as [string, RequestInit];
+    expect(url).toBe(
+      // `#` in the membershipKey MUST be URL-encoded — otherwise the
+      // server sees a fragment, not a path segment.
+      "https://vault.test.example.com/v1/memberships/psn_1%23cmp_abc/sync-config",
+    );
+    expect(init.method).toBe("GET");
+    expect(init.body).toBeUndefined();
+  });
+
+  it("returns the default row (isDefault: true) without updatedAt/updatedBy", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, {
+        membershipId: "psn_1#cmp_abc",
+        syncMode: "all",
+        isDefault: true,
+      }),
+    );
+
+    const result = await client.getMembershipSyncConfig("psn_1#cmp_abc");
+    expect(result.isDefault).toBe(true);
+    expect(result.updatedAt).toBeUndefined();
+    expect(result.updatedBy).toBeUndefined();
+  });
+
+  it("maps 401 to VaultAuthError", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(401, { error: "Token expired" }),
+    );
+
+    await expect(
+      client.getMembershipSyncConfig("psn_1#cmp_abc"),
+    ).rejects.toThrow(VaultAuthError);
+  });
+
+  it("maps 404 to VaultNotFoundError (membership tombstoned or missing)", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(404, {
+        error: "Membership not found or not active: psn_1#cmp_abc",
+      }),
+    );
+
+    await expect(
+      client.getMembershipSyncConfig("psn_1#cmp_abc"),
+    ).rejects.toThrow(VaultNotFoundError);
+  });
+
+  it("surfaces network errors after retry exhaustion", async () => {
+    fetchSpy.mockRejectedValue(new Error("socket hang up"));
+
+    await expect(
+      client.getMembershipSyncConfig("psn_1#cmp_abc"),
+    ).rejects.toThrow(/socket hang up/);
+    expect(fetchSpy).toHaveBeenCalledTimes(4);
+  });
+});
+
+describe("setMembershipSyncConfig (US-004)", () => {
+  it("PUTs the partial body to /v1/memberships/{id}/sync-config", async () => {
+    const persisted: MembershipSyncConfig = {
+      membershipId: "psn_1#cmp_abc",
+      syncMode: "custom",
+      customPaths: ["shared/docs"],
+      isDefault: false,
+      updatedAt: "2026-05-20T12:00:00.000Z",
+      updatedBy: "psn_1",
+    };
+    fetchSpy.mockResolvedValueOnce(jsonResponse(200, persisted));
+
+    const result = await client.setMembershipSyncConfig("psn_1#cmp_abc", {
+      syncMode: "custom",
+      customPaths: ["shared/docs"],
+    });
+
+    expect(result).toEqual(persisted);
+
+    const [url, init] = fetchSpy.mock.calls[0] as [string, RequestInit];
+    expect(url).toBe(
+      "https://vault.test.example.com/v1/memberships/psn_1%23cmp_abc/sync-config",
+    );
+    expect(init.method).toBe("PUT");
+    const headers = init.headers as Record<string, string>;
+    expect(headers["Content-Type"]).toBe("application/json");
+    expect(headers.Authorization).toBe("Bearer test-jwt-token-123");
+    expect(JSON.parse(init.body as string)).toEqual({
+      syncMode: "custom",
+      customPaths: ["shared/docs"],
+    });
+  });
+
+  it("supports the shared mode without customPaths", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, {
+        membershipId: "psn_1#cmp_abc",
+        syncMode: "shared",
+        isDefault: false,
+        updatedAt: "2026-05-20T12:00:00.000Z",
+        updatedBy: "psn_1",
+      }),
+    );
+
+    const result = await client.setMembershipSyncConfig("psn_1#cmp_abc", {
+      syncMode: "shared",
+    });
+
+    expect(result.syncMode).toBe("shared");
+    expect(result.customPaths).toBeUndefined();
+
+    const [, init] = fetchSpy.mock.calls[0] as [string, RequestInit];
+    expect(JSON.parse(init.body as string)).toEqual({ syncMode: "shared" });
+  });
+
+  it("maps 401 to VaultAuthError", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(401, { error: "Token expired" }),
+    );
+
+    await expect(
+      client.setMembershipSyncConfig("psn_1#cmp_abc", { syncMode: "all" }),
+    ).rejects.toThrow(VaultAuthError);
+  });
+
+  it("maps 404 to VaultNotFoundError when the membership is gone", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(404, { error: "Membership not found" }),
+    );
+
+    await expect(
+      client.setMembershipSyncConfig("psn_1#cmp_abc", { syncMode: "all" }),
+    ).rejects.toThrow(VaultNotFoundError);
+  });
+
+  it("maps 409 to VaultConflictError", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(409, { error: "Concurrent write conflict" }),
+    );
+
+    await expect(
+      client.setMembershipSyncConfig("psn_1#cmp_abc", { syncMode: "all" }),
+    ).rejects.toThrow(VaultConflictError);
+  });
+
+  it("surfaces network errors after retry exhaustion", async () => {
+    fetchSpy.mockRejectedValue(new Error("ETIMEDOUT"));
+
+    await expect(
+      client.setMembershipSyncConfig("psn_1#cmp_abc", { syncMode: "all" }),
+    ).rejects.toThrow(/ETIMEDOUT/);
+    expect(fetchSpy).toHaveBeenCalledTimes(4);
+  });
+});
+
 // ---------------------------------------------------------------------------
 // Refreshable authToken getter
 //
@@ -787,3 +1046,79 @@ describe("authToken getter (refreshable token)", () => {
     }
   });
 });
+
+// ---------------------------------------------------------------------------
+// Raw vend (POST /vend, purpose-aware after US-009)
+// ---------------------------------------------------------------------------
+
+describe("vend (POST /vend, purpose-aware)", () => {
+  it("POSTs to /vend with paths/operations/purpose and returns credentials + policySize", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, {
+        credentials: {
+          accessKeyId: "AKIA-BROWSE",
+          secretAccessKey: "secret",
+          sessionToken: "token",
+          expiration: "2026-05-20T13:00:00.000Z",
+        },
+        paths: ["shared/docs/"],
+        operations: "read-only",
+        purpose: "browse",
+        policySize: 412,
+        requestId: "req_xyz",
+      }),
+    );
+
+    const out = await client.vend({
+      paths: ["shared/docs/"],
+      operations: "read-only",
+      purpose: "browse",
+    });
+
+    expect(out.purpose).toBe("browse");
+    expect(out.policySize).toBe(412);
+    expect(out.credentials.accessKeyId).toBe("AKIA-BROWSE");
+    expect(out.credentials.sessionToken).toBe("token");
+
+    const [url, init] = fetchSpy.mock.calls[0] as [string, RequestInit];
+    expect(url).toBe("https://vault.test.example.com/vend");
+    expect((init.method as string).toUpperCase()).toBe("POST");
+    expect(JSON.parse(init.body as string)).toEqual({
+      paths: ["shared/docs/"],
+      operations: "read-only",
+      purpose: "browse",
+    });
+  });
+
+  it("forwards purpose='sync' verbatim (no client-side defaulting)", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, {
+        credentials: {
+          accessKeyId: "k",
+          secretAccessKey: "s",
+          sessionToken: "t",
+          expiration: "2026-05-20T13:00:00.000Z",
+        },
+        paths: ["shared/"],
+        operations: "read-only",
+        purpose: "sync",
+        policySize: 200,
+      }),
+    );
+
+    await client.vend({
+      paths: ["shared/"],
+      operations: "read-only",
+      purpose: "sync",
+      duration: 1800,
+    });
+
+    const [, init] = fetchSpy.mock.calls[0] as [string, RequestInit];
+    expect(JSON.parse(init.body as string)).toEqual({
+      paths: ["shared/"],
+      operations: "read-only",
+      purpose: "sync",
+      duration: 1800,
+    });
+  });
+});