@vellumai/credential-executor 0.10.7-dev.202607102035.64f07ea → 0.10.7-staging.1

package/src/__tests__/managed-lazy-getters.test.ts

@@ -0,0 +1,359 @@
+/**
+ * Tests for the managed CES lazy API key getter pattern.
+ *
+ * Exercises the production `buildLazyGetters` from `managed-lazy-getters.ts`
+ * directly, ensuring regressions in key precedence, lazy resolution, or
+ * graceful degradation are caught by these tests.
+ */
+
+import { describe, expect, test } from "bun:test";
+
+import {
+  applyManagedCredentialRefs,
+  buildLazyGetters,
+  type ApiKeyRef,
+  type AssistantIdRef,
+} from "../managed-lazy-getters.js";
+
+// ---------------------------------------------------------------------------
+// applyManagedCredentialRefs — fail-closed overwrite across sessions
+// ---------------------------------------------------------------------------
+
+describe("applyManagedCredentialRefs", () => {
+  test("overwrites both refs with the provided values", () => {
+    const apiKeyRef: ApiKeyRef = { current: "old-key" };
+    const assistantIdRef: AssistantIdRef = { current: "ast_old" };
+
+    applyManagedCredentialRefs(apiKeyRef, assistantIdRef, "new-key", "ast_new");
+
+    expect(apiKeyRef.current).toBe("new-key");
+    expect(assistantIdRef.current).toBe("ast_new");
+  });
+
+  test("clears a stale assistant ID when the new value is omitted", () => {
+    // A new session (or an API-key-only update) that does not carry an
+    // assistant ID must not inherit the previous session's ID.
+    const apiKeyRef: ApiKeyRef = { current: "prev-key" };
+    const assistantIdRef: AssistantIdRef = { current: "ast_prev" };
+
+    applyManagedCredentialRefs(
+      apiKeyRef,
+      assistantIdRef,
+      "rotated-key",
+      undefined,
+    );
+
+    expect(apiKeyRef.current).toBe("rotated-key");
+    expect(assistantIdRef.current).toBe("");
+  });
+
+  test("clears a stale API key when the new value is omitted", () => {
+    const apiKeyRef: ApiKeyRef = { current: "prev-key" };
+    const assistantIdRef: AssistantIdRef = { current: "ast_prev" };
+
+    applyManagedCredentialRefs(apiKeyRef, assistantIdRef, undefined, undefined);
+
+    expect(apiKeyRef.current).toBe("");
+    expect(assistantIdRef.current).toBe("");
+  });
+
+  test("lazy getters fail closed after a reconnect that omits the ID", () => {
+    const apiKeyRef: ApiKeyRef = { current: "session1-key" };
+    const assistantIdRef: AssistantIdRef = { current: "ast_session1" };
+    const { getManagedMaterializerOptions } = buildLazyGetters({
+      platformBaseUrl: "https://api.vellum.ai",
+      assistantIdRef,
+      apiKeyRef,
+    });
+
+    // A reconnecting session provides a key but no assistant ID.
+    applyManagedCredentialRefs(
+      apiKeyRef,
+      assistantIdRef,
+      "session2-key",
+      undefined,
+    );
+
+    // Materialization must not proceed with the prior session's assistant ID.
+    expect(getManagedMaterializerOptions()).toBeUndefined();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Before API key arrives
+// ---------------------------------------------------------------------------
+
+describe("managed lazy getters — before API key arrives", () => {
+  test("apiKeyRef starts empty and managed subject options are undefined", () => {
+    const apiKeyRef: ApiKeyRef = { current: "" };
+    const assistantIdRef: AssistantIdRef = { current: "ast_abc123" };
+    const { getManagedSubjectOptions } = buildLazyGetters({
+      platformBaseUrl: "https://api.vellum.ai",
+      assistantIdRef,
+      apiKeyRef,
+    });
+
+    expect(apiKeyRef.current).toBe("");
+    expect(getManagedSubjectOptions()).toBeUndefined();
+  });
+
+  test("apiKeyRef starts empty and managed materializer options are undefined", () => {
+    const apiKeyRef: ApiKeyRef = { current: "" };
+    const assistantIdRef: AssistantIdRef = { current: "ast_abc123" };
+    const { getManagedMaterializerOptions } = buildLazyGetters({
+      platformBaseUrl: "https://api.vellum.ai",
+      assistantIdRef,
+      apiKeyRef,
+    });
+
+    expect(getManagedMaterializerOptions()).toBeUndefined();
+  });
+
+  test("getAssistantApiKey returns empty string when ref is empty and no env var", () => {
+    const apiKeyRef: ApiKeyRef = { current: "" };
+    const assistantIdRef: AssistantIdRef = { current: "ast_abc123" };
+    const { getAssistantApiKey } = buildLazyGetters({
+      platformBaseUrl: "https://api.vellum.ai",
+      assistantIdRef,
+      apiKeyRef,
+    });
+
+    expect(getAssistantApiKey()).toBe("");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// After API key arrives via handshake
+// ---------------------------------------------------------------------------
+
+describe("managed lazy getters — after API key arrives via handshake", () => {
+  test("setting apiKeyRef.current enables managed subject options", () => {
+    const apiKeyRef: ApiKeyRef = { current: "" };
+    const assistantIdRef: AssistantIdRef = { current: "ast_abc123" };
+    const { getManagedSubjectOptions } = buildLazyGetters({
+      platformBaseUrl: "https://api.vellum.ai",
+      assistantIdRef,
+      apiKeyRef,
+    });
+
+    expect(getManagedSubjectOptions()).toBeUndefined();
+
+    apiKeyRef.current = "vak_test_key_12345";
+
+    const opts = getManagedSubjectOptions();
+    expect(opts).toBeDefined();
+    expect(opts!.platformBaseUrl).toBe("https://api.vellum.ai");
+    expect(opts!.assistantApiKey).toBe("vak_test_key_12345");
+    expect(opts!.assistantId).toBe("ast_abc123");
+  });
+
+  test("setting apiKeyRef.current enables managed materializer options", () => {
+    const apiKeyRef: ApiKeyRef = { current: "" };
+    const assistantIdRef: AssistantIdRef = { current: "ast_abc123" };
+    const { getManagedMaterializerOptions } = buildLazyGetters({
+      platformBaseUrl: "https://api.vellum.ai",
+      assistantIdRef,
+      apiKeyRef,
+    });
+
+    expect(getManagedMaterializerOptions()).toBeUndefined();
+
+    apiKeyRef.current = "vak_test_key_12345";
+
+    const opts = getManagedMaterializerOptions();
+    expect(opts).toBeDefined();
+    expect(opts!.platformBaseUrl).toBe("https://api.vellum.ai");
+    expect(opts!.assistantApiKey).toBe("vak_test_key_12345");
+    expect(opts!.assistantId).toBe("ast_abc123");
+  });
+
+  test("returned options contain the exact key from the ref (not a stale copy)", () => {
+    const apiKeyRef: ApiKeyRef = { current: "" };
+    const assistantIdRef: AssistantIdRef = { current: "ast_abc123" };
+    const { getManagedSubjectOptions, getManagedMaterializerOptions } =
+      buildLazyGetters({
+        platformBaseUrl: "https://api.vellum.ai",
+        assistantIdRef,
+        apiKeyRef,
+      });
+
+    apiKeyRef.current = "vak_key_v1";
+    expect(getManagedSubjectOptions()!.assistantApiKey).toBe("vak_key_v1");
+    expect(getManagedMaterializerOptions()!.assistantApiKey).toBe("vak_key_v1");
+
+    apiKeyRef.current = "vak_key_v2";
+    expect(getManagedSubjectOptions()!.assistantApiKey).toBe("vak_key_v2");
+    expect(getManagedMaterializerOptions()!.assistantApiKey).toBe("vak_key_v2");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Lazy resolution timing
+// ---------------------------------------------------------------------------
+
+describe("managed lazy getters — lazy resolution timing", () => {
+  test("handlers built before key arrives resolve the key at call time", () => {
+    const apiKeyRef: ApiKeyRef = { current: "" };
+    const assistantIdRef: AssistantIdRef = { current: "ast_abc123" };
+
+    const { getManagedSubjectOptions, getManagedMaterializerOptions } =
+      buildLazyGetters({
+        platformBaseUrl: "https://api.vellum.ai",
+        assistantIdRef,
+        apiKeyRef,
+      });
+
+    // At registration time: no key yet
+    expect(getManagedSubjectOptions()).toBeUndefined();
+    expect(getManagedMaterializerOptions()).toBeUndefined();
+
+    // Later: handshake delivers the key
+    apiKeyRef.current = "vak_late_arriving_key";
+
+    // Same getter functions now return valid options
+    expect(getManagedSubjectOptions()).toBeDefined();
+    expect(getManagedMaterializerOptions()).toBeDefined();
+    expect(getManagedSubjectOptions()!.assistantApiKey).toBe(
+      "vak_late_arriving_key",
+    );
+  });
+
+  test("deps object with getter properties resolves lazily (mirrors httpDeps pattern)", () => {
+    const apiKeyRef: ApiKeyRef = { current: "" };
+    const assistantIdRef: AssistantIdRef = { current: "ast_abc123" };
+    const { getManagedSubjectOptions, getManagedMaterializerOptions } =
+      buildLazyGetters({
+        platformBaseUrl: "https://api.vellum.ai",
+        assistantIdRef,
+        apiKeyRef,
+      });
+
+    // Build a deps object with getters, mirroring managed-main.ts httpDeps
+    const httpDeps = {
+      get managedSubjectOptions() {
+        return getManagedSubjectOptions();
+      },
+      get managedMaterializerOptions() {
+        return getManagedMaterializerOptions();
+      },
+    };
+
+    // Before key: both undefined
+    expect(httpDeps.managedSubjectOptions).toBeUndefined();
+    expect(httpDeps.managedMaterializerOptions).toBeUndefined();
+
+    // After key: both resolved
+    apiKeyRef.current = "vak_lazy_key";
+    expect(httpDeps.managedSubjectOptions).toBeDefined();
+    expect(httpDeps.managedSubjectOptions!.assistantApiKey).toBe(
+      "vak_lazy_key",
+    );
+    expect(httpDeps.managedMaterializerOptions).toBeDefined();
+    expect(httpDeps.managedMaterializerOptions!.assistantApiKey).toBe(
+      "vak_lazy_key",
+    );
+  });
+
+  test("env var fallback is used when ref is empty", () => {
+    const apiKeyRef: ApiKeyRef = { current: "" };
+    const assistantIdRef: AssistantIdRef = { current: "ast_abc123" };
+    const { getAssistantApiKey, getManagedSubjectOptions } = buildLazyGetters({
+      platformBaseUrl: "https://api.vellum.ai",
+      assistantIdRef,
+      apiKeyRef,
+      envApiKey: "vak_env_fallback",
+    });
+
+    expect(getAssistantApiKey()).toBe("vak_env_fallback");
+    expect(getManagedSubjectOptions()).toBeDefined();
+    expect(getManagedSubjectOptions()!.assistantApiKey).toBe(
+      "vak_env_fallback",
+    );
+  });
+
+  test("handshake-provided key takes precedence over env var", () => {
+    const apiKeyRef: ApiKeyRef = { current: "" };
+    const assistantIdRef: AssistantIdRef = { current: "ast_abc123" };
+    const { getAssistantApiKey } = buildLazyGetters({
+      platformBaseUrl: "https://api.vellum.ai",
+      assistantIdRef,
+      apiKeyRef,
+      envApiKey: "vak_env_key",
+    });
+
+    expect(getAssistantApiKey()).toBe("vak_env_key");
+
+    apiKeyRef.current = "vak_handshake_key";
+    expect(getAssistantApiKey()).toBe("vak_handshake_key");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Missing required fields -> undefined (graceful degradation)
+// ---------------------------------------------------------------------------
+
+describe("managed lazy getters — missing platform config fields", () => {
+  test("missing platformBaseUrl returns undefined even with API key", () => {
+    const apiKeyRef: ApiKeyRef = { current: "vak_test_key" };
+    const assistantIdRef: AssistantIdRef = { current: "ast_abc123" };
+    const { getManagedSubjectOptions, getManagedMaterializerOptions } =
+      buildLazyGetters({
+        platformBaseUrl: "",
+        assistantIdRef,
+        apiKeyRef,
+      });
+
+    expect(getManagedSubjectOptions()).toBeUndefined();
+    expect(getManagedMaterializerOptions()).toBeUndefined();
+  });
+
+  test("missing assistantId returns undefined even with API key", () => {
+    const apiKeyRef: ApiKeyRef = { current: "vak_test_key" };
+    const assistantIdRef: AssistantIdRef = { current: "" };
+    const { getManagedSubjectOptions, getManagedMaterializerOptions } =
+      buildLazyGetters({
+        platformBaseUrl: "https://api.vellum.ai",
+        assistantIdRef,
+        apiKeyRef,
+      });
+
+    expect(getManagedSubjectOptions()).toBeUndefined();
+    expect(getManagedMaterializerOptions()).toBeUndefined();
+  });
+
+  test("assistantIdRef updated after build enables options (warm-pool scenario)", () => {
+    /**
+     * Verifies that updating assistantIdRef.current after buildLazyGetters
+     * makes previously-undefined options become defined — the core fix for
+     * warm-pool pods where the assistant ID is empty at CES startup.
+     */
+
+    // GIVEN an API key is available but assistant ID is empty (warm-pool startup)
+    const apiKeyRef: ApiKeyRef = { current: "vak_test_key" };
+    const assistantIdRef: AssistantIdRef = { current: "" };
+    const { getManagedSubjectOptions, getManagedMaterializerOptions } =
+      buildLazyGetters({
+        platformBaseUrl: "https://api.vellum.ai",
+        assistantIdRef,
+        apiKeyRef,
+      });
+
+    // WHEN options are checked before assistant ID arrives
+    // THEN they are undefined
+    expect(getManagedSubjectOptions()).toBeUndefined();
+    expect(getManagedMaterializerOptions()).toBeUndefined();
+
+    // WHEN the assistant ID arrives via handshake/RPC
+    assistantIdRef.current = "ast_provisioned_123";
+
+    // THEN the same getter functions now return valid options
+    const subOpts = getManagedSubjectOptions();
+    expect(subOpts).toBeDefined();
+    expect(subOpts!.assistantId).toBe("ast_provisioned_123");
+    expect(subOpts!.assistantApiKey).toBe("vak_test_key");
+
+    const matOpts = getManagedMaterializerOptions();
+    expect(matOpts).toBeDefined();
+    expect(matOpts!.assistantId).toBe("ast_provisioned_123");
+  });
+});