@indigoai-us/hq-cloud 5.1.10 → 5.1.12

package/src/bin/sync-runner.ts

@@ -54,8 +54,24 @@ import type {
   SyncResult,
   SyncProgressEvent,
 } from "../cli/sync.js";
+import { share as defaultShare } from "../cli/share.js";
+import type { ShareOptions, ShareResult } from "../cli/share.js";
 import type { ConflictStrategy } from "../cli/conflict.js";
 
+/**
+ * Sync direction for a run.
+ *
+ * - `pull`: download-only (legacy `hq sync` behaviour, and the default for
+ *   back-compat with pre-5.1.11 callers of the runner).
+ * - `push`: upload-only. Walks the company folder and sends every file whose
+ *   local hash differs from the journal (skipUnchanged).
+ * - `both`: push first, then pull. "Sync Now" in the menubar app targets this.
+ *   Push runs first so the subsequent pull doesn't redownload files we were
+ *   about to replace; if a company aborts on push conflict, pull is skipped
+ *   for that company but the fanout continues.
+ */
+export type Direction = "pull" | "push" | "both";
+
 // ---------------------------------------------------------------------------
 // Defaults — mirror `hq-cli/src/utils/cognito-session.ts`. Inlined (not
 // imported) to avoid a circular dep between hq-cli and hq-cloud. If these
@@ -65,8 +81,8 @@ import type { ConflictStrategy } from "../cli/conflict.js";
 
 const DEFAULT_COGNITO: CognitoAuthConfig = {
   region: process.env.AWS_REGION ?? "us-east-1",
-  userPoolDomain: process.env.HQ_COGNITO_DOMAIN ?? "hq-vault-dev",
-  clientId: process.env.HQ_COGNITO_CLIENT_ID ?? "4mmujmjq3srakdueg656b9m0mp",
+  userPoolDomain: process.env.HQ_COGNITO_DOMAIN ?? "vault-indigo-hq-dev",
+  clientId: process.env.HQ_COGNITO_CLIENT_ID ?? "7r7an9keh0u6hlsvepl74tvqb0",
   port: process.env.HQ_COGNITO_CALLBACK_PORT
     ? Number(process.env.HQ_COGNITO_CALLBACK_PORT)
     : 8765,
@@ -74,7 +90,7 @@ const DEFAULT_COGNITO: CognitoAuthConfig = {
 
 const DEFAULT_VAULT_API_URL =
   process.env.HQ_VAULT_API_URL ??
-  "https://tqdwdqxv75.execute-api.us-east-1.amazonaws.com";
+  "https://ky8cgbl4yh.execute-api.us-east-1.amazonaws.com";
 
 const DEFAULT_HQ_ROOT = path.join(os.homedir(), "hq");
 
@@ -97,12 +113,27 @@ export type RunnerEvent =
     }
   | ({ type: "progress"; company: string } & Omit<Extract<SyncProgressEvent, { type: "progress" }>, "type">)
   | ({ type: "error"; company?: string } & Omit<Extract<SyncProgressEvent, { type: "error" }>, "type">)
-  | ({ type: "complete"; company: string } & SyncResult)
+  | ({
+      type: "complete";
+      company: string;
+      /**
+       * Upload counters. Always emitted (0 when the run was pull-only) so
+       * downstream consumers don't need to conditionally read the field.
+       * Tauri's `SyncCompleteEvent` ignores extra fields today; adding them
+       * to the Rust struct is a follow-up when the UI needs to surface push
+       * totals.
+       */
+      filesUploaded: number;
+      bytesUploaded: number;
+    } & SyncResult)
   | {
       type: "all-complete";
       companiesAttempted: number;
       filesDownloaded: number;
       bytesDownloaded: number;
+      /** Always emitted; 0 when no push phase ran. */
+      filesUploaded: number;
+      bytesUploaded: number;
       errors: Array<{ company: string; message: string }>;
     };
 
@@ -158,6 +189,8 @@ export interface RunnerDeps {
   createVaultClient?: (config: VaultServiceConfig) => VaultClientSurface;
   /** Sync function. Defaults to `cli/sync.sync`. */
   sync?: (options: SyncOptions) => Promise<SyncResult>;
+  /** Share function (push phase). Defaults to `cli/share.share`. */
+  share?: (options: ShareOptions) => Promise<ShareResult>;
 }
 
 // ---------------------------------------------------------------------------
@@ -239,6 +272,7 @@ interface ParsedArgs {
   company?: string;
   onConflict: ConflictStrategy;
   hqRoot: string;
+  direction: Direction;
 }
 
 function parseArgs(argv: string[]): ParsedArgs | { error: string } {
@@ -246,6 +280,7 @@ function parseArgs(argv: string[]): ParsedArgs | { error: string } {
   let company: string | undefined;
   let onConflict: ConflictStrategy = "abort";
   let hqRoot = DEFAULT_HQ_ROOT;
+  let direction: Direction = "pull";
 
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
@@ -267,6 +302,16 @@ function parseArgs(argv: string[]): ParsedArgs | { error: string } {
         onConflict = val;
         break;
       }
+      case "--direction": {
+        const val = argv[++i];
+        if (val !== "pull" && val !== "push" && val !== "both") {
+          return {
+            error: `--direction must be one of pull|push|both, got: ${val ?? "(missing)"}`,
+          };
+        }
+        direction = val;
+        break;
+      }
       case "--hq-root":
         hqRoot = argv[++i];
         if (!hqRoot) return { error: "--hq-root requires a value" };
@@ -286,7 +331,7 @@ function parseArgs(argv: string[]): ParsedArgs | { error: string } {
     return { error: "Pass --companies or --company <slug>" };
   }
 
-  return { companies, company, onConflict, hqRoot };
+  return { companies, company, onConflict, hqRoot, direction };
 }
 
 // ---------------------------------------------------------------------------
@@ -402,42 +447,99 @@ export async function runRunner(
 
   // ---- fanout -----------------------------------------------------------
   const syncFn = deps.sync ?? defaultSync;
-  let totalFiles = 0;
-  let totalBytes = 0;
+  const shareFn = deps.share ?? defaultShare;
+  const doPush = parsed.direction === "push" || parsed.direction === "both";
+  const doPull = parsed.direction === "pull" || parsed.direction === "both";
+  let totalDownloaded = 0;
+  let totalDownloadedBytes = 0;
+  let totalUploaded = 0;
+  let totalUploadedBytes = 0;
   const errors: Array<{ company: string; message: string }> = [];
 
   for (const target of plan) {
     const companyLabel = target.slug;
+    // Per-company event tagger — shared by push and pull phases so progress
+    // rows land on the right company regardless of which phase emitted them.
+    const tagAndEmit = (event: SyncProgressEvent): void => {
+      if (event.type === "progress") {
+        emit({
+          type: "progress",
+          company: companyLabel,
+          path: event.path,
+          bytes: event.bytes,
+          ...(event.message ? { message: event.message } : {}),
+        });
+      } else {
+        emit({
+          type: "error",
+          company: companyLabel,
+          path: event.path,
+          message: event.message,
+        });
+      }
+    };
+
     try {
-      const result = await syncFn({
-        company: target.uid,
-        vaultConfig,
-        hqRoot: parsed.hqRoot,
-        onConflict: parsed.onConflict,
-        onEvent: (event) => {
-          // Tag per-file events with the company they belong to so the
-          // menubar can route them to the right company's progress bar.
-          if (event.type === "progress") {
-            emit({
-              type: "progress",
-              company: companyLabel,
-              path: event.path,
-              bytes: event.bytes,
-              ...(event.message ? { message: event.message } : {}),
-            });
-          } else {
-            emit({
-              type: "error",
-              company: companyLabel,
-              path: event.path,
-              message: event.message,
-            });
-          }
-        },
+      let pushResult: ShareResult = {
+        filesUploaded: 0,
+        bytesUploaded: 0,
+        filesSkipped: 0,
+        aborted: false,
+      };
+      let pullResult: SyncResult = {
+        filesDownloaded: 0,
+        bytesDownloaded: 0,
+        filesSkipped: 0,
+        conflicts: 0,
+        aborted: false,
+      };
+
+      // Push first so a subsequent pull doesn't overwrite files we were about
+      // to broadcast. Uses the walk-everything-under-companies/{slug}/ entry
+      // point with `skipUnchanged` so we don't re-upload files that haven't
+      // changed since the last sync.
+      if (doPush) {
+        pushResult = await shareFn({
+          paths: [path.join(parsed.hqRoot, "companies", target.slug)],
+          company: target.uid,
+          vaultConfig,
+          hqRoot: parsed.hqRoot,
+          onConflict: parsed.onConflict,
+          skipUnchanged: true,
+          onEvent: tagAndEmit,
+        });
+      }
+
+      // Pull runs unless the push phase aborted on conflict — aborted means
+      // the user has local edits + remote drift; blindly pulling would erase
+      // whichever side `--on-conflict abort` just protected.
+      if (doPull && !pushResult.aborted) {
+        pullResult = await syncFn({
+          company: target.uid,
+          vaultConfig,
+          hqRoot: parsed.hqRoot,
+          onConflict: parsed.onConflict,
+          onEvent: tagAndEmit,
+        });
+      }
+
+      emit({
+        type: "complete",
+        company: companyLabel,
+        filesDownloaded: pullResult.filesDownloaded,
+        bytesDownloaded: pullResult.bytesDownloaded,
+        filesUploaded: pushResult.filesUploaded,
+        bytesUploaded: pushResult.bytesUploaded,
+        filesSkipped: pullResult.filesSkipped + pushResult.filesSkipped,
+        conflicts: pullResult.conflicts,
+        // Either phase aborting marks the company aborted — the UI treats
+        // `aborted: true` as "sync didn't complete cleanly for this company".
+        aborted: pullResult.aborted || pushResult.aborted,
       });
-      emit({ type: "complete", company: companyLabel, ...result });
-      totalFiles += result.filesDownloaded;
-      totalBytes += result.bytesDownloaded;
+      totalDownloaded += pullResult.filesDownloaded;
+      totalDownloadedBytes += pullResult.bytesDownloaded;
+      totalUploaded += pushResult.filesUploaded;
+      totalUploadedBytes += pushResult.bytesUploaded;
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);
       errors.push({ company: companyLabel, message });
@@ -454,8 +556,10 @@ export async function runRunner(
   emit({
     type: "all-complete",
     companiesAttempted: plan.length,
-    filesDownloaded: totalFiles,
-    bytesDownloaded: totalBytes,
+    filesDownloaded: totalDownloaded,
+    bytesDownloaded: totalDownloadedBytes,
+    filesUploaded: totalUploaded,
+    bytesUploaded: totalUploadedBytes,
     errors,
   });
   return 0;

package/src/cli/share.test.ts

@@ -198,4 +198,146 @@ describe("share", () => {
 
     expect(result.filesUploaded).toBe(1);
   });
+
+  it("skipUnchanged=true skips files whose local hash matches the journal", async () => {
+    const companyRoot = path.join(tmpDir, "companies", "acme");
+    fs.mkdirSync(companyRoot, { recursive: true });
+    const testFile = path.join(companyRoot, "unchanged.md");
+    fs.writeFileSync(testFile, "stable content");
+
+    // Precompute the hash of the file so the journal matches exactly.
+    const { hashFile } = await import("../journal.js");
+    const hash = hashFile(testFile);
+
+    const journalPath = path.join(stateDir, "sync-journal.acme.json");
+    fs.writeFileSync(
+      journalPath,
+      JSON.stringify({
+        version: "1",
+        lastSync: new Date().toISOString(),
+        files: {
+          "unchanged.md": {
+            hash,
+            size: 15,
+            syncedAt: new Date().toISOString(),
+            direction: "up",
+          },
+        },
+      }),
+    );
+
+    const result = await share({
+      paths: [testFile],
+      company: "acme",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+      skipUnchanged: true,
+    });
+
+    expect(result.filesUploaded).toBe(0);
+    expect(result.filesSkipped).toBe(1);
+    expect(uploadFile).not.toHaveBeenCalled();
+  });
+
+  it("skipUnchanged=true still uploads files whose hash differs from the journal", async () => {
+    const companyRoot = path.join(tmpDir, "companies", "acme");
+    fs.mkdirSync(companyRoot, { recursive: true });
+    const testFile = path.join(companyRoot, "changed.md");
+    fs.writeFileSync(testFile, "new content");
+
+    // Journal has a stale hash for this path — simulating "local has been
+    // edited since the last push".
+    const journalPath = path.join(stateDir, "sync-journal.acme.json");
+    fs.writeFileSync(
+      journalPath,
+      JSON.stringify({
+        version: "1",
+        lastSync: new Date().toISOString(),
+        files: {
+          "changed.md": {
+            hash: "stale-hash-from-previous-sync",
+            size: 10,
+            syncedAt: new Date().toISOString(),
+            direction: "up",
+          },
+        },
+      }),
+    );
+
+    const result = await share({
+      paths: [testFile],
+      company: "acme",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+      skipUnchanged: true,
+    });
+
+    expect(result.filesUploaded).toBe(1);
+    expect(uploadFile).toHaveBeenCalledWith(expect.anything(), testFile, "changed.md");
+  });
+
+  it("skipUnchanged=false (default) uploads even when hash matches", async () => {
+    const companyRoot = path.join(tmpDir, "companies", "acme");
+    fs.mkdirSync(companyRoot, { recursive: true });
+    const testFile = path.join(companyRoot, "unchanged.md");
+    fs.writeFileSync(testFile, "stable content");
+
+    const { hashFile } = await import("../journal.js");
+    const hash = hashFile(testFile);
+
+    const journalPath = path.join(stateDir, "sync-journal.acme.json");
+    fs.writeFileSync(
+      journalPath,
+      JSON.stringify({
+        version: "1",
+        lastSync: new Date().toISOString(),
+        files: {
+          "unchanged.md": {
+            hash,
+            size: 15,
+            syncedAt: new Date().toISOString(),
+            direction: "up",
+          },
+        },
+      }),
+    );
+
+    const result = await share({
+      paths: [testFile],
+      company: "acme",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+      // skipUnchanged omitted — preserves `hq share <file>` semantics
+    });
+
+    expect(result.filesUploaded).toBe(1);
+    expect(uploadFile).toHaveBeenCalled();
+  });
+
+  it("onEvent receives progress events instead of console output", async () => {
+    const companyRoot = path.join(tmpDir, "companies", "acme");
+    fs.mkdirSync(companyRoot, { recursive: true });
+    fs.writeFileSync(path.join(companyRoot, "a.md"), "aaa");
+    fs.writeFileSync(path.join(companyRoot, "b.md"), "bbb");
+
+    const events: Array<{ type: string; path: string; bytes?: number }> = [];
+    const result = await share({
+      paths: [companyRoot],
+      company: "acme",
+      vaultConfig: mockConfig,
+      hqRoot: tmpDir,
+      onEvent: (e) => {
+        events.push({
+          type: e.type,
+          path: e.path,
+          ...(e.type === "progress" ? { bytes: e.bytes } : {}),
+        });
+      },
+    });
+
+    expect(result.filesUploaded).toBe(2);
+    expect(events).toHaveLength(2);
+    expect(events.every((e) => e.type === "progress")).toBe(true);
+    expect(events.map((e) => e.path).sort()).toEqual(["a.md", "b.md"]);
+  });
 });

package/src/cli/share.ts

@@ -14,6 +14,7 @@ import { readJournal, writeJournal, hashFile, updateEntry } from "../journal.js"
 import { createIgnoreFilter, isWithinSizeLimit } from "../ignore.js";
 import { resolveConflict } from "./conflict.js";
 import type { ConflictStrategy } from "./conflict.js";
+import type { SyncProgressEvent } from "./sync.js";
 
 export interface ShareOptions {
   /** Path(s) to share (files or directories) */
@@ -28,6 +29,23 @@ export interface ShareOptions {
   vaultConfig: VaultServiceConfig;
   /** HQ root directory */
   hqRoot: string;
+  /**
+   * Per-file event callback. When present, suppresses the default
+   * `console.log`/`console.error` human output — same contract as `sync()`.
+   * This is the seam `hq-sync-runner` uses to stream ndjson for push events.
+   */
+  onEvent?: (event: SyncProgressEvent) => void;
+  /**
+   * When true, files whose local hash matches the journal entry from the
+   * last sync are skipped (no remote HEAD, no upload). This is the gate
+   * that makes "push everything that changed" efficient — without it, a
+   * bidirectional Sync Now would re-upload every file each tick.
+   *
+   * Default false to preserve `hq share <file>` semantics: when a user
+   * explicitly names a file, they expect it to be sent even if the local
+   * hash matches the last-sync state (e.g. to re-heal a bucket).
+   */
+  skipUnchanged?: boolean;
 }
 
 export interface ShareResult {
@@ -41,7 +59,8 @@ export interface ShareResult {
  * Share local file(s) to the entity vault.
  */
 export async function share(options: ShareOptions): Promise<ShareResult> {
-  const { paths, company, message, onConflict, vaultConfig, hqRoot } = options;
+  const { paths, company, message, onConflict, vaultConfig, hqRoot, skipUnchanged } = options;
+  const emit = options.onEvent ?? defaultConsoleLogger;
 
   // Resolve company — slug, UID, or from active config
   const companyRef = company ?? resolveActiveCompany(hqRoot);
@@ -70,11 +89,28 @@ export async function share(options: ShareOptions): Promise<ShareResult> {
 
   for (const { absolutePath, relativePath } of filesToShare) {
     if (!isWithinSizeLimit(absolutePath)) {
-      console.error(`  Skipped (too large): ${relativePath}`);
+      emit({
+        type: "error",
+        path: relativePath,
+        message: "file exceeds size limit",
+      });
       filesSkipped++;
       continue;
     }
 
+    // Skip-if-unchanged gate: the hot path for bidirectional Sync Now. When
+    // walking an entire company folder, this is what keeps us from re-uploading
+    // every file every tick. Off by default so `hq share <file>` keeps its
+    // explicit-intent semantics (user named it, user wants it sent).
+    const localHash = hashFile(absolutePath);
+    if (skipUnchanged) {
+      const existing = journal.files[relativePath];
+      if (existing && existing.hash === localHash) {
+        filesSkipped++;
+        continue;
+      }
+    }
+
     // Auto-refresh context if credentials expiring
     if (isExpiringSoon(ctx.expiresAt)) {
       ctx = await refreshEntityContext(companyRef, vaultConfig);
@@ -84,7 +120,6 @@ export async function share(options: ShareOptions): Promise<ShareResult> {
     const remoteMeta = await headRemoteFile(ctx, relativePath);
     if (remoteMeta) {
       const journalEntry = journal.files[relativePath];
-      const localHash = hashFile(absolutePath);
 
       // If remote has changed since our last sync, it's a conflict
       if (journalEntry && journalEntry.hash !== localHash) {
@@ -113,12 +148,11 @@ export async function share(options: ShareOptions): Promise<ShareResult> {
     // Upload
     try {
       const stat = fs.statSync(absolutePath);
-      const hash = hashFile(absolutePath);
 
       await uploadFile(ctx, absolutePath, relativePath);
 
       // Update journal with optional message
-      updateEntry(journal, relativePath, hash, stat.size, "up");
+      updateEntry(journal, relativePath, localHash, stat.size, "up");
       if (message) {
         journal.files[relativePath] = {
           ...journal.files[relativePath],
@@ -128,11 +162,18 @@ export async function share(options: ShareOptions): Promise<ShareResult> {
 
       filesUploaded++;
       bytesUploaded += stat.size;
-      console.log(`  ✓ ${relativePath}`);
+      emit({
+        type: "progress",
+        path: relativePath,
+        bytes: stat.size,
+        ...(message ? { message } : {}),
+      });
     } catch (err) {
-      console.error(
-        `  ✗ ${relativePath} — ${err instanceof Error ? err.message : err}`,
-      );
+      emit({
+        type: "error",
+        path: relativePath,
+        message: err instanceof Error ? err.message : String(err),
+      });
     }
   }
 
@@ -141,6 +182,22 @@ export async function share(options: ShareOptions): Promise<ShareResult> {
   return { filesUploaded, bytesUploaded, filesSkipped, aborted: false };
 }
 
+/**
+ * Default human-readable share output. Preserves the exact format the CLI
+ * emitted before `onEvent` was added — tty users see no change.
+ */
+function defaultConsoleLogger(event: SyncProgressEvent): void {
+  if (event.type === "progress") {
+    if (event.message) {
+      console.log(`  ✓ ${event.path} — "${event.message}"`);
+    } else {
+      console.log(`  ✓ ${event.path}`);
+    }
+  } else {
+    console.error(`  ✗ ${event.path} — ${event.message}`);
+  }
+}
+
 /**
  * Resolve active company from .hq/config.json or parent directory chain.
  */

package/src/cognito-auth.test.ts

@@ -146,7 +146,7 @@ describe("expiresAt shape round-trip", () => {
     const result = await refreshTokens(
       {
         region: "us-east-1",
-        userPoolDomain: "hq-vault-dev",
+        userPoolDomain: "vault-indigo-hq-dev",
         clientId: "test-client",
       },
       "prior-refresh-token",

package/src/cognito-auth.ts

@@ -30,9 +30,9 @@ import open from "open";
 export interface CognitoAuthConfig {
   /** AWS region the User Pool lives in (e.g. "us-east-1"). */
   region: string;
-  /** Cognito User Pool Domain prefix (e.g. "vault-indigo-stefanjohnson"). */
+  /** Cognito User Pool Domain prefix (e.g. "vault-indigo-hq-dev"). */
   userPoolDomain: string;
-  /** App Client ID (e.g. "4mmujmjq3srakdueg656b9m0mp"). */
+  /** App Client ID (e.g. "7r7an9keh0u6hlsvepl74tvqb0"). */
   clientId: string;
   /** Loopback callback port. Defaults to 3000. */
   port?: number;

package/src/vault-client.test.ts

@@ -560,4 +560,89 @@ describe("VaultClient identity bootstrap", () => {
     const body = JSON.parse(init.body as string);
     expect(body.slug).toBe("user-12345678");
   });
+
+  it("listByType_roundtrips_createdAt", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, {
+        entities: [
+          {
+            uid: "prs_x",
+            slug: "alice",
+            type: "person",
+            status: "active",
+            createdAt: "2026-01-01T00:00:00Z",
+          },
+        ],
+      }),
+    );
+
+    const entities = await client.entity.listByType("person");
+    expect(entities).toHaveLength(1);
+    expect(entities[0].createdAt).toBe("2026-01-01T00:00:00Z");
+  });
+
+  it("ensureMyPersonEntity_picks_oldest_when_multiple", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, {
+        entities: [
+          { uid: "prs_b", slug: "b", type: "person", status: "active", createdAt: "2026-03-01T00:00:00Z" },
+          { uid: "prs_a", slug: "a", type: "person", status: "active", createdAt: "2026-01-01T00:00:00Z" },
+          { uid: "prs_c", slug: "c", type: "person", status: "active", createdAt: "2026-06-01T00:00:00Z" },
+        ],
+      }),
+    );
+
+    const person = await client.ensureMyPersonEntity({
+      ownerSub: "sub-multi",
+      displayName: "Multi User",
+    });
+
+    expect(person.uid).toBe("prs_a");
+    expect(fetchSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it("ensureMyPersonEntity_handles_missing_createdAt_deterministically", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, {
+        entities: [
+          { uid: "prs_z", slug: "z", type: "person", status: "active" },
+          { uid: "prs_a", slug: "a", type: "person", status: "active" },
+        ],
+      }),
+    );
+
+    const person = await client.ensureMyPersonEntity({
+      ownerSub: "sub-nodates",
+      displayName: "No Dates User",
+    });
+
+    // Both missing createdAt → "" tie, uid tiebreak selects prs_a
+    expect(person.uid).toBe("prs_a");
+    expect(fetchSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it("vendSelf_roundtrip", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, {
+        credentials: {
+          accessKeyId: "AKIAIOSFODNN7EXAMPLE",
+          secretAccessKey: "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
+          sessionToken: "FwoGZXIvYXdzEBY...",
+        },
+        expiresAt: "2026-01-01T01:00:00.000Z",
+      }),
+    );
+
+    const result = await client.sts.vendSelf({ personUid: "prs_x" });
+
+    expect(result.credentials.accessKeyId).toBe("AKIAIOSFODNN7EXAMPLE");
+    expect(result.credentials.secretAccessKey).toBe("wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY");
+    expect(result.credentials.sessionToken).toBe("FwoGZXIvYXdzEBY...");
+    expect(typeof result.expiresAt).toBe("string");
+
+    const [url, init] = fetchSpy.mock.calls[0] as [string, RequestInit];
+    expect(url).toBe("https://vault.test.example.com/sts/vend-self");
+    expect((init.method as string).toUpperCase()).toBe("POST");
+    expect(JSON.parse(init.body as string)).toEqual({ personUid: "prs_x" });
+  });
 });