Skip to content

OpenRAG is a comprehensive, single package Retrieval-Augmented Generation platform built on Langflow, Docling, and Opensearch.

Python
39.9 KB
Raw Blame
/**
 * Integration tests for OpenRAG TypeScript SDK.
 *
 * These tests run against a real OpenRAG instance.
 * Requires: OPENRAG_URL environment variable (defaults to http://localhost:3000)
 *
 * Run with: npm test
 */

import { describe, it, expect, beforeAll, afterAll } from "vitest";
import * as fs from "fs";
import * as path from "path";
import * as os from "os";
import type { DoneEvent, StreamEvent } from "../src";

// Dynamic import to handle the SDK not being built yet
let OpenRAGClient: typeof import("../src").OpenRAGClient;
let ValidationError: typeof import("../src").ValidationError;
let NotFoundError: typeof import("../src").NotFoundError;
let AuthenticationError: typeof import("../src").AuthenticationError;

const BASE_URL = process.env.OPENRAG_URL || "http://localhost:3000";
const SKIP_TESTS = process.env.SKIP_SDK_INTEGRATION_TESTS === "true";

// Ensure the OpenRAG instance is onboarded before running tests
async function ensureOnboarding(): Promise<void> {
  const azureKey = process.env.AZURE_OPENAI_API_KEY || process.env.AZURE_API_KEY;
  const azureEndpoint =
    process.env.AZURE_OPENAI_ENDPOINT ||
    process.env.AZURE_OPENAI_API_BASE ||
    process.env.AZURE_API_BASE;
  const azureVersion =
    process.env.AZURE_OPENAI_API_VERSION || process.env.AZURE_API_VERSION;
  const useAzure = Boolean(azureKey || process.env.LLM_PROVIDER === "azure");

  const llmProvider =
    process.env.LLM_PROVIDER || (useAzure ? "azure" : "openai");
  const embeddingProvider =
    process.env.EMBEDDING_PROVIDER || (useAzure ? "azure" : "openai");
  const llmModel =
    process.env.LLM_MODEL ||
    (llmProvider === "azure" ? "gpt-4.1" : "gpt-4o-mini");
  const embeddingModel = process.env.EMBEDDING_MODEL || "text-embedding-3-small";

  const onboardingPayload: Record<string, any> = {
    llm_provider: llmProvider,
    embedding_provider: embeddingProvider,
    embedding_model: embeddingModel,
    llm_model: llmModel,
  };
  if (azureKey && azureEndpoint) {
    const creds: Record<string, string> = {
      api_key: azureKey,
      api_base: azureEndpoint,
    };
    if (azureVersion) creds.api_version = azureVersion;
    onboardingPayload.provider_credentials = { azure: creds };
  }

  try {
    const response = await fetch(`${BASE_URL}/api/onboarding`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify(onboardingPayload),
    });

    if (response.status === 200 || response.status === 204) {
      console.log("[SDK Tests] Onboarding completed successfully");
    } else {
      // May already be onboarded, which is fine
      const text = await response.text();
      console.log(`[SDK Tests] Onboarding returned ${response.status}: ${text.slice(0, 200)}`);
    }
  } catch (e) {
    console.log(`[SDK Tests] Onboarding request failed: ${e}`);
  }
}

// Create API key for tests
async function createApiKey(): Promise<string> {
  // Use /api/keys to go through frontend proxy (frontend at :3000 proxies /api/* to backend)
  const response = await fetch(`${BASE_URL}/api/keys`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ name: "TypeScript SDK Integration Test" }),
  });

  if (response.status === 401) {
    throw new Error("Cannot create API key - authentication required");
  }

  if (!response.ok) {
    throw new Error(`Failed to create API key: ${await response.text()}`);
  }

  const data = await response.json();
  return data.api_key;
}

// Create test file
function createTestFile(): string {
  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "sdk-test-"));
  const filePath = path.join(tmpDir, "sdk_test_doc.md");
  fs.writeFileSync(
    filePath,
    "# SDK Integration Test Document\n\n" +
      "This document tests the OpenRAG TypeScript SDK.\n" +
      "It contains unique content about orange kangaroos jumping.\n"
  );
  return filePath;
}

describe.skipIf(SKIP_TESTS)("OpenRAG TypeScript SDK Integration", () => {
  let client: InstanceType<typeof OpenRAGClient>;
  let testFilePath: string;

  beforeAll(async () => {
    // Ensure onboarding is done first (marks config as edited)
    await ensureOnboarding();

    // Import SDK
    const sdk = await import("../src");
    OpenRAGClient = sdk.OpenRAGClient;
    ValidationError = sdk.ValidationError;
    NotFoundError = sdk.NotFoundError;
    AuthenticationError = sdk.AuthenticationError;

    // Create API key and client
    const apiKey = await createApiKey();
    client = new OpenRAGClient({ apiKey, baseUrl: BASE_URL });

    // Create test file
    testFilePath = createTestFile();
  });

  describe("Auth", () => {
    it("constructs without an apiKey when extraHeaders are provided, and extraHeaders authenticate real requests", async () => {
      // Mirrors IBM SaaS-style auth, where a gateway injects headers instead of
      // an SDK-level api key. The TS client has no api-key-or-extraHeaders
      // construction check (unlike the Python SDK), so this call is expected to
      // succeed unconditionally; what we're really proving is that a request
      // authenticated purely via extraHeaders (no `apiKey` option at all) goes
      // through end-to-end. We forward a real API key via extraHeaders rather
      // than IBM-specific X-Username/X-Api-Key headers, since those only
      // authenticate when the server has IBM auth mode enabled, which isn't
      // guaranteed in a generic test environment — _getHeaders() in client.ts
      // merges extraHeaders in verbatim, so this exercises the exact same
      // "auth carried entirely by extraHeaders" code path deterministically.
      const apiKey = await createApiKey();

      let extraHeadersClient: InstanceType<typeof OpenRAGClient>;
      expect(() => {
        extraHeadersClient = new OpenRAGClient({
          baseUrl: BASE_URL,
          extraHeaders: { "X-API-Key": apiKey },
        });
      }).not.toThrow();

      const settings = await extraHeadersClient!.settings.get();
      expect(settings.agent).toBeDefined();
      expect(settings.knowledge).toBeDefined();
    });

    it("an invalid API key raises AuthenticationError with statusCode 401/403", async () => {
      const badClient = new OpenRAGClient({
        apiKey: "orag_invalid_key_for_testing",
        baseUrl: BASE_URL,
      });

      let threw = false;
      try {
        await badClient.settings.get();
      } catch (e) {
        threw = true;
        expect(e).toBeInstanceOf(AuthenticationError);
        expect([401, 403]).toContain((e as InstanceType<typeof AuthenticationError>).statusCode);
      }
      expect(threw).toBe(true);
    });
  });

  describe("Settings", () => {
    it("should get settings", async () => {
      const settings = await client.settings.get();

      expect(settings.agent).toBeDefined();
      expect(settings.knowledge).toBeDefined();

      // Newly-typed fields (types.ts) — type-or-null/undefined checks, mirroring
      // how chunk_size is treated elsewhere in this block (may not be set yet).
      expect(
        settings.knowledge.chunk_overlap === undefined ||
          settings.knowledge.chunk_overlap === null ||
          typeof settings.knowledge.chunk_overlap === "number"
      ).toBe(true);
      expect(
        settings.knowledge.table_structure === undefined ||
          settings.knowledge.table_structure === null ||
          typeof settings.knowledge.table_structure === "boolean"
      ).toBe(true);
      expect(
        settings.knowledge.ocr === undefined ||
          settings.knowledge.ocr === null ||
          typeof settings.knowledge.ocr === "boolean"
      ).toBe(true);
      expect(
        settings.knowledge.picture_descriptions === undefined ||
          settings.knowledge.picture_descriptions === null ||
          typeof settings.knowledge.picture_descriptions === "boolean"
      ).toBe(true);
      expect(
        settings.agent.system_prompt === undefined ||
          settings.agent.system_prompt === null ||
          typeof settings.agent.system_prompt === "string"
      ).toBe(true);
    });

    it("should update settings", async () => {
      // Get current settings first
      const currentSettings = await client.settings.get();
      const currentChunkSize = currentSettings.knowledge.chunk_size || 1000;

      // Update with a new value
      const result = await client.settings.update({
        chunk_size: currentChunkSize,
      });

      expect(result.message).toBeDefined();

      // Verify the setting persisted
      const updatedSettings = await client.settings.get();
      expect(updatedSettings.knowledge.chunk_size).toBe(currentChunkSize);
    });
  });

  describe("Knowledge Filters", () => {
    let createdFilterId: string;

    it("should create a knowledge filter", async () => {
      const result = await client.knowledgeFilters.create({
        name: "SDK Test Filter",
        description: "Filter created by TypeScript SDK integration tests",
        queryData: {
          query: "test documents",
          limit: 10,
          scoreThreshold: 0.5,
        },
      });

      expect(result.success).toBe(true);
      expect(result.id).toBeDefined();
      createdFilterId = result.id!;
    });

    it("should search knowledge filters", async () => {
      const filters = await client.knowledgeFilters.search("SDK Test");

      expect(Array.isArray(filters)).toBe(true);
      // Should find the filter we created
      const found = filters.some((f) => f.name === "SDK Test Filter");
      expect(found).toBe(true);
    });

    it("should return an empty array when a knowledge filter search matches nothing", async () => {
      const filters = await client.knowledgeFilters.search(
        `zzzz_no_such_filter_${Date.now()}_qqqq`
      );
      expect(filters).toEqual([]);
    });

    it("should respect the limit param on knowledge filter search", async () => {
      const filters = await client.knowledgeFilters.search("", 1);
      expect(filters.length).toBeLessThanOrEqual(1);
    });

    it("should get a knowledge filter by ID", async () => {
      expect(createdFilterId).toBeDefined();

      const filter = await client.knowledgeFilters.get(createdFilterId);

      expect(filter).not.toBeNull();
      expect(filter!.id).toBe(createdFilterId);
      expect(filter!.name).toBe("SDK Test Filter");
      expect(filter!.queryData).toBeDefined();
      expect(filter!.queryData.query).toBe("test documents");
      expect(typeof filter!.owner).toBe("string");
      expect(typeof filter!.createdAt).toBe("string");
      expect(typeof filter!.updatedAt).toBe("string");
    });

    it("should update a knowledge filter", async () => {
      expect(createdFilterId).toBeDefined();

      const success = await client.knowledgeFilters.update(createdFilterId, {
        description: "Updated description from SDK test",
      });

      expect(success).toBe(true);

      // Verify the update
      const filter = await client.knowledgeFilters.get(createdFilterId);
      expect(filter!.description).toBe("Updated description from SDK test");
    });

    it("should delete a knowledge filter", async () => {
      expect(createdFilterId).toBeDefined();

      const success = await client.knowledgeFilters.delete(createdFilterId);

      expect(success).toBe(true);

      // Verify deletion
      const filter = await client.knowledgeFilters.get(createdFilterId);
      expect(filter).toBeNull();
    });

    it("create() fails when the required name field is missing", async () => {
      // `name` is required by CreateKnowledgeFilterOptions; bypass the type
      // system with `as any` to exercise server-side validation. Per
      // knowledge-filters.ts, create() does not catch request errors, so a
      // server-side 400 surfaces as a thrown ValidationError rather than a
      // `{ success: false }` response — but we also accept the latter shape
      // in case the server instead responds 200 with success:false.
      try {
        const result = await client.knowledgeFilters.create({
          description: "Missing required name field",
          queryData: { query: "test" },
          // eslint-disable-next-line @typescript-eslint/no-explicit-any
        } as any);
        expect(result.success).toBe(false);
        expect(result.error).toBeTruthy();
      } catch (e) {
        expect((e as Error).message).toBeTruthy();
      }
    });

    it("filterId in chat actually scopes retrieval to data_sources", async () => {
      // Ingest two distinguishable docs.
      const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "sdk-filter-"));
      const alphaName = `alpha_${Date.now()}.md`;
      const betaName = `beta_${Date.now()}.md`;
      const alphaPath = path.join(tmpDir, alphaName);
      const betaPath = path.join(tmpDir, betaName);
      fs.writeFileSync(alphaPath, "# Alpha\n\nPurple elephants live here.\n");
      fs.writeFileSync(betaPath, "# Beta\n\nYellow tigers live here.\n");
      await client.documents.ingest({ filePath: alphaPath });
      await client.documents.ingest({ filePath: betaPath });

      const createResult = await client.knowledgeFilters.create({
        name: `TS chat filter scope ${Date.now()}`,
        description: "Filter scoped to alpha only",
        queryData: {
          query: "",
          filters: {
            data_sources: [alphaName],
            document_types: ["*"],
            owners: ["*"],
            connector_types: ["*"],
          },
          limit: 10,
          scoreThreshold: 0,
        },
      });
      expect(createResult.success).toBe(true);
      const filterId = createResult.id!;

      try {
        const response = await client.chat.create({
          message: "What animals appear in these documents?",
          filterId,
        });
        expect(response.sources).toBeDefined();
        const names = (response.sources ?? []).map((s) => s.filename);
        // Beta must NOT leak through the filter.
        expect(names).not.toContain(betaName);
      } finally {
        await client.knowledgeFilters.delete(filterId);
        await client.documents.delete(alphaName);
        await client.documents.delete(betaName);
      }
    }, 120_000);

    it("filterId in search actually scopes results to data_sources", async () => {
      const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "sdk-filter-"));
      const alphaName = `alpha_${Date.now()}.md`;
      const betaName = `beta_${Date.now()}.md`;
      const alphaPath = path.join(tmpDir, alphaName);
      const betaPath = path.join(tmpDir, betaName);
      fs.writeFileSync(alphaPath, "# Alpha\n\nPurple elephants live here.\n");
      fs.writeFileSync(betaPath, "# Beta\n\nYellow tigers live here.\n");
      await client.documents.ingest({ filePath: alphaPath });
      await client.documents.ingest({ filePath: betaPath });

      const createResult = await client.knowledgeFilters.create({
        name: `TS search filter scope ${Date.now()}`,
        description: "Filter scoped to alpha only",
        queryData: {
          query: "",
          filters: {
            data_sources: [alphaName],
            document_types: ["*"],
            owners: ["*"],
            connector_types: ["*"],
          },
          limit: 10,
          scoreThreshold: 0,
        },
      });
      expect(createResult.success).toBe(true);
      const filterId = createResult.id!;

      try {
        const results = await client.search.query("animals", { filterId });
        for (const r of results.results) {
          expect(r.filename).not.toBe(betaName);
        }
      } finally {
        await client.knowledgeFilters.delete(filterId);
        await client.documents.delete(alphaName);
        await client.documents.delete(betaName);
      }
    }, 120_000);

    it("documents.delete(filterId) only removes filenames in the filter", async () => {
      const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "sdk-filter-"));
      const alphaName = `alpha_${Date.now()}.md`;
      const betaName = `beta_${Date.now()}.md`;
      const alphaPath = path.join(tmpDir, alphaName);
      const betaPath = path.join(tmpDir, betaName);
      fs.writeFileSync(alphaPath, "# Alpha\n\nPurple elephants.\n");
      fs.writeFileSync(betaPath, "# Beta\n\nYellow tigers.\n");
      await client.documents.ingest({ filePath: alphaPath });
      await client.documents.ingest({ filePath: betaPath });

      const createResult = await client.knowledgeFilters.create({
        name: `TS delete-by-filter ${Date.now()}`,
        description: "Filter scoped to alpha only",
        queryData: {
          query: "",
          filters: {
            data_sources: [alphaName],
            document_types: ["*"],
            owners: ["*"],
            connector_types: ["*"],
          },
          limit: 10,
          scoreThreshold: 0,
        },
      });
      expect(createResult.success).toBe(true);
      const filterId = createResult.id!;

      try {
        const result = await client.documents.delete({ filterId });
        expect(result.success).toBe(true);
        expect(result.filenames).toContain(alphaName);
        expect(result.filenames ?? []).not.toContain(betaName);
        // per_file has one entry per resolved data_source (see types.ts).
        expect(Array.isArray(result.per_file)).toBe(true);
        expect(result.per_file!.length).toBe(result.filenames!.length);

        // Beta still searchable
        const remaining = await client.search.query("tigers");
        const remainingNames = remaining.results.map((r) => r.filename);
        expect(remainingNames).toContain(betaName);
      } finally {
        await client.knowledgeFilters.delete(filterId);
        await client.documents.delete(alphaName);
        await client.documents.delete(betaName);
      }
    }, 120_000);

    it("documents.delete rejects both filename and filterId together", async () => {
      await expect(
        client.documents.delete({ filename: "x.pdf", filterId: "y" })
      ).rejects.toThrow();
    });

    it("documents.delete rejects when neither arg is set", async () => {
      await expect(client.documents.delete({})).rejects.toThrow();
    });
  });

  describe("Documents", () => {
    // Filenames ingested by this block that must be removed afterwards so
    // they don't leak into subsequent test runs.
    const createdFilenames: string[] = [];

    afterAll(async () => {
      const uniqueFilenames = Array.from(new Set(createdFilenames));
      for (const filename of uniqueFilenames) {
        try {
          await client.documents.delete(filename);
        } catch {
          // Best-effort cleanup; some of these may already be deleted by
          // the tests themselves.
        }
      }
    });

    it("should ingest a document (wait for completion)", async () => {
      // wait=true (default) polls until completion
      const result = await client.documents.ingest({ filePath: testFilePath });
      createdFilenames.push(path.basename(testFilePath));

      // TODO: Fix Langflow ingestion flow - currently returns 0 successful files
      // due to embedding model component errors in layer 0
      expect(result.status).toBeDefined();
      expect((result as any).successful_files).toBeGreaterThanOrEqual(0);
      expect((result as any).total_files).toBeGreaterThanOrEqual(0);
      expect((result as any).processed_files).toBeGreaterThanOrEqual(0);
      expect((result as any).failed_files).toBeGreaterThanOrEqual(0);
    }, 120_000);

    it("should ingest a document without waiting", async () => {
      // wait=false returns immediately with task_id
      const result = await client.documents.ingest({
        filePath: testFilePath,
        wait: false,
      });
      createdFilenames.push(path.basename(testFilePath));

      expect((result as any).task_id).toBeDefined();

      // Can poll manually
      const finalStatus = await client.documents.waitForTask(
        (result as any).task_id
      );
      // TODO: Fix Langflow ingestion - status may be "failed" due to flow issues
      expect(finalStatus.status).toBeDefined();
    });

    it("waitForTask throws when timeout elapses before any poll", async () => {
      // Racing a real task's duration (e.g. a small nonzero timeout) is
      // inherently flaky: if the task reaches a terminal status on the very
      // first poll -- which can happen near-instantly, including on failure
      // -- waitForTask resolves normally instead of throwing, regardless of
      // how small the timeout was. timeout=0 makes the elapsed<timeoutMs loop
      // guard false before the first poll, so this is deterministic and
      // doesn't require a real ingest (the task id is never even queried).
      await expect(
        client.documents.waitForTask("nonexistent-id", 0.1, 0)
      ).rejects.toThrow();
    });

    it("getTaskStatus throws NotFoundError (404) for a nonexistent task", async () => {
      let threw = false;
      try {
        await client.documents.getTaskStatus("nonexistent-id");
      } catch (e) {
        threw = true;
        expect(e).toBeInstanceOf(NotFoundError);
        expect((e as InstanceType<typeof NotFoundError>).statusCode).toBe(404);
      }
      expect(threw).toBe(true);
    });

    it("delete({ filterId }) throws NotFoundError for a nonexistent filter id", async () => {
      await expect(
        client.documents.delete({ filterId: "nonexistent-uuid-like-value" })
      ).rejects.toThrow(NotFoundError);
    });

    it("should delete a document", async () => {
      // Use a uniquely named file so this test doesn't inherit chunks left in
      // the index by the two ingest tests above (which share testFilePath /
      // "sdk_test_doc.md"). Otherwise a zero-successful-files re-ingest here can
      // still find the earlier document, making delete succeed when the
      // else-branch expects a no-op — i.e. ingest's reported successful_files
      // would no longer reflect whether THIS document exists in the index.
      const deleteDir = fs.mkdtempSync(path.join(os.tmpdir(), "sdk-del-"));
      const deleteFilePath = path.join(
        deleteDir,
        `sdk_delete_doc_${Date.now()}.md`
      );
      fs.writeFileSync(
        deleteFilePath,
        "# SDK Delete Test Document\n\n" +
          "This document tests document deletion via the OpenRAG TypeScript SDK.\n" +
          "It contains unique content about teal dolphins swimming.\n"
      );
      const deleteFilename = path.basename(deleteFilePath);
      createdFilenames.push(deleteFilename);

      // First ingest (wait for completion)
      const ingestResult = await client.documents.ingest({
        filePath: deleteFilePath,
      });

      // Make ingestion deterministically succeed before asserting delete
      // behavior — fail clearly instead of branching the assertions below on
      // whether ingestion happened to index anything.
      if (
        !("successful_files" in ingestResult) ||
        ingestResult.successful_files <= 0
      ) {
        throw new Error(
          `Ingestion did not index any files for ${deleteFilename} ` +
            `(successful_files=${
              "successful_files" in ingestResult
                ? ingestResult.successful_files
                : "unknown"
            }); cannot verify delete behavior deterministically.`
        );
      }

      // Then delete
      const result = await client.documents.delete(deleteFilename);

      expect(result.success).toBe(true);
      expect(result.deleted_chunks).toBeGreaterThan(0);
    });

    it("should treat delete of missing document as idempotent", async () => {
      const missingFilename = `never_ingested_${Date.now()}_${Math.random()
        .toString(16)
        .slice(2)}.pdf`;

      const result = await client.documents.delete(missingFilename);

      expect(result.success).toBe(false);
      expect(result.deleted_chunks).toBe(0);
      expect(result.filename).toBe(missingFilename);
      expect(result.error).toBeDefined();
    });
  });

  describe("Search", () => {
    it("should search documents", async () => {
      // Documents already ingested by previous tests
      const results = await client.search.query("orange kangaroos jumping");

      expect(results.results).toBeDefined();
      expect(Array.isArray(results.results)).toBe(true);
      for (const r of results.results) {
        // score is a raw OpenSearch relevance score (boosted BM25/KNN
        // hybrid), not normalized to [0, 1] -- it can exceed 1.
        expect(r.score).toBeGreaterThanOrEqual(0);
      }
    });

    it("should return an empty array for a query guaranteed not to match", async () => {
      // search_service.py only applies OpenSearch's `min_score` filter when
      // score_threshold > 0 (the default is 0, which applies no filter at
      // all). Since search is hybrid BM25+KNN, an unfiltered nonsense query
      // still returns nearest-neighbor hits -- nothing is "guaranteed not to
      // match" without an explicit threshold. Reuse the same 0.5 cutoff the
      // "should respect scoreThreshold" test below treats as meaningful.
      const results = await client.search.query(
        `zzzz_no_such_content_${Date.now()}_qqqq`,
        { scoreThreshold: 0.5 }
      );
      expect(results.results).toEqual([]);
    });

    it("should respect scoreThreshold", async () => {
      const results = await client.search.query("orange kangaroos jumping", {
        scoreThreshold: 0.5,
      });
      expect(results.results.every((r) => r.score >= 0.5)).toBe(true);
    });

    it("should respect limit", async () => {
      const results = await client.search.query("orange kangaroos jumping", {
        limit: 5,
      });
      expect(results.results.length).toBeLessThanOrEqual(5);
    });

    it("should filter search by filename via data_sources", async () => {
      // Ingest two distinguishable docs, then wildcard-search scoped to one
      // filename so the assertion does not depend on semantic ranking.
      const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "sdk-search-filter-"));
      const token = Date.now();
      const alphaName = `alpha_${token}.md`;
      const betaName = `beta_${token}.md`;
      const alphaPath = path.join(tmpDir, alphaName);
      const betaPath = path.join(tmpDir, betaName);
      fs.writeFileSync(alphaPath, "# Alpha\n\nUnique content about purple elephants.\n");
      fs.writeFileSync(betaPath, "# Beta\n\nUnique content about yellow tigers.\n");
      await client.documents.ingest({ filePath: alphaPath });
      await client.documents.ingest({ filePath: betaPath });

      try {
        const results = await client.search.query("*", {
          filters: { data_sources: [alphaName] },
        });
        const filenames = results.results.map((r) => r.filename);
        expect(filenames).toContain(alphaName);
        expect(filenames).not.toContain(betaName);
        for (const r of results.results) {
          expect(r.filename).toBe(alphaName);
        }
      } finally {
        await client.documents.delete(alphaName);
        await client.documents.delete(betaName);
      }
    }, 120_000);

    it("should reject a whitespace-only query", async () => {
      // ASSUMPTION (not verified against a live instance in this environment):
      // the backend rejects blank/whitespace-only search queries with a 400,
      // which the SDK surfaces as ValidationError. search.ts performs no
      // client-side validation of its own, so this test's outcome depends
      // entirely on server-side behavior. If the server does NOT reject
      // whitespace queries, this test will fail and the validation should be
      // added server-side (or this expectation revisited).
      await expect(client.search.query("   ")).rejects.toThrow(ValidationError);
    });

    it("should include page and mimetype fields with correct optional types", async () => {
      const results = await client.search.query("orange kangaroos jumping");
      for (const r of results.results) {
        expect(
          r.page === undefined || r.page === null || typeof r.page === "number"
        ).toBe(true);
        expect(
          r.mimetype === undefined ||
            r.mimetype === null ||
            typeof r.mimetype === "string"
        ).toBe(true);
      }
    });
  });

  describe("Chat", () => {
    // Conversations created by this block that must be cleaned up.
    const createdChatIds: string[] = [];

    afterAll(async () => {
      const uniqueIds = Array.from(new Set(createdChatIds));
      for (const chatId of uniqueIds) {
        try {
          await client.chat.delete(chatId);
        } catch {
          // Best-effort cleanup.
        }
      }
    });

    it("should send non-streaming chat", async () => {
      const response = await client.chat.create({
        message: "Say hello in exactly 3 words.",
      });

      expect(response.response).toBeDefined();
      expect(typeof response.response).toBe("string");
      expect(response.response.length).toBeGreaterThan(0);

      for (const source of response.sources ?? []) {
        expect(typeof source.filename).toBe("string");
        expect(typeof source.text).toBe("string");
        expect(typeof source.score).toBe("number");
        // score is a raw OpenSearch relevance score (boosted BM25/KNN
        // hybrid), not normalized to [0, 1] -- it can exceed 1.
        expect(source.score).toBeGreaterThanOrEqual(0);
      }

      if (response.chatId) {
        createdChatIds.push(response.chatId);
      }
    });

    it("should combine filters, limit, and scoreThreshold in one chat.create() call", async () => {
      const response = await client.chat.create({
        message: "What documents mention kangaroos?",
        filters: { data_sources: [path.basename(testFilePath)] },
        limit: 3,
        scoreThreshold: 0,
      });

      expect(response.response).toBeDefined();
      expect(typeof response.response).toBe("string");

      if (response.chatId) {
        createdChatIds.push(response.chatId);
      }
    });

    it("should stream chat with create({ stream: true })", async () => {
      let collectedText = "";
      const events: StreamEvent[] = [];

      for await (const event of await client.chat.create({
        message: "Say 'test' and nothing else.",
        stream: true,
      })) {
        events.push(event);
        if (event.type === "content") {
          collectedText += event.delta;
        }
      }

      expect(collectedText.length).toBeGreaterThan(0);

      // A "done" event must be observed and must be the LAST event collected.
      const doneEvents = events.filter((e) => e.type === "done");
      expect(doneEvents.length).toBeGreaterThanOrEqual(1);
      const lastEvent = events[events.length - 1];
      expect(lastEvent?.type).toBe("done");

      const doneEvent = doneEvents[doneEvents.length - 1] as DoneEvent;
      expect(doneEvent.chatId).toBeDefined();
      if (doneEvent.chatId) {
        createdChatIds.push(doneEvent.chatId);
      }
    });

    it("should stream chat with stream() context manager", async () => {
      const stream = await client.chat.stream({
        message: "Say 'hello' and nothing else.",
      });

      try {
        for await (const _ of stream) {
          // Consume stream
        }

        expect(stream.text.length).toBeGreaterThan(0);
        expect(stream.chatId).toBeDefined();
        expect(typeof stream.chatId).toBe("string");
        if (stream.chatId) {
          createdChatIds.push(stream.chatId);
        }
      } finally {
        stream.close();
      }
    });

    it("consuming a ChatStream twice throws", async () => {
      const stream = await client.chat.stream({
        message: "Say 'twice' and nothing else.",
      });

      try {
        for await (const _ of stream) {
          // Consume once, fully.
        }
        if (stream.chatId) {
          createdChatIds.push(stream.chatId);
        }

        await expect(async () => {
          for await (const _ of stream) {
            // no-op; should throw before yielding anything
          }
        }).rejects.toThrow();
      } finally {
        stream.close();
      }
    });

    it("should use textStream helper", async () => {
      let collected = "";

      const stream = await client.chat.stream({
        message: "Say 'world' and nothing else.",
      });

      try {
        for await (const text of stream.textStream) {
          collected += text;
        }

        expect(collected.length).toBeGreaterThan(0);
        if (stream.chatId) {
          createdChatIds.push(stream.chatId);
        }
      } finally {
        stream.close();
      }
    });

    it("should use finalText() helper", async () => {
      const stream = await client.chat.stream({
        message: "Say 'done' and nothing else.",
      });

      try {
        const text = await stream.finalText();
        expect(text.length).toBeGreaterThan(0);
        if (stream.chatId) {
          createdChatIds.push(stream.chatId);
        }
      } finally {
        stream.close();
      }
    });

    it("should continue a conversation", async () => {
      // First message
      const response1 = await client.chat.create({
        message: "Remember the number 99.",
      });
      expect(response1.chatId).toBeDefined();

      // Continue conversation
      const response2 = await client.chat.create({
        message: "What number did I ask you to remember?",
        chatId: response1.chatId!,
      });
      expect(response2.response).toBeDefined();
      expect(response2.chatId).toBe(response1.chatId);

      if (response1.chatId) {
        createdChatIds.push(response1.chatId);
      }
    });

    it("should list conversations", async () => {
      // Create a conversation first
      const created = await client.chat.create({ message: "Test message for listing." });
      if (created.chatId) {
        createdChatIds.push(created.chatId);
      }

      // List conversations
      const result = await client.chat.list();

      expect(result.conversations).toBeDefined();
      expect(Array.isArray(result.conversations)).toBe(true);
      expect(result.conversations.length).toBeGreaterThan(0);

      for (const conversation of result.conversations) {
        expect(typeof conversation.chatId).toBe("string");
        expect(typeof conversation.createdAt).toBe("string");
        expect(conversation.createdAt!.length).toBeGreaterThan(0);
        expect(typeof conversation.lastActivity).toBe("string");
        expect(conversation.lastActivity!.length).toBeGreaterThan(0);
        expect(typeof conversation.messageCount).toBe("number");
        expect(conversation.messageCount).toBeGreaterThanOrEqual(0);
      }
    });

    it("should get a specific conversation", async () => {
      // Create a conversation first
      const response = await client.chat.create({
        message: "Test message for get.",
      });
      expect(response.chatId).toBeDefined();
      if (response.chatId) {
        createdChatIds.push(response.chatId);
      }

      // Get the conversation
      const conversation = await client.chat.get(response.chatId!);

      expect(conversation.chatId).toBe(response.chatId);
      expect(conversation.messages).toBeDefined();
      expect(Array.isArray(conversation.messages)).toBe(true);
      expect(conversation.messages.length).toBeGreaterThanOrEqual(1);

      for (const message of conversation.messages) {
        expect(["user", "assistant"]).toContain(message.role);
        expect(typeof message.content).toBe("string");
      }
    });

    it("should delete a conversation", async () => {
      // Create a conversation first
      const response = await client.chat.create({
        message: "Test message for delete.",
      });
      expect(response.chatId).toBeDefined();

      // Delete the conversation
      const result = await client.chat.delete(response.chatId!);

      expect(result).toBe(true);
    });

    it("deleting a nonexistent conversation throws NotFoundError", async () => {
      // Unlike Python's chat.delete() (chat.py), which explicitly catches
      // NotFoundError and returns False for idempotency, chat.ts's delete()
      // has no such catch and lets the 404 propagate. This asserts TS's
      // actual current behavior; the cross-SDK inconsistency (Python is
      // idempotent here, TS is not) is worth aligning in a follow-up.
      await expect(
        client.chat.delete(`nonexistent-chat-${Date.now()}`)
      ).rejects.toThrow(NotFoundError);
    });
  });

  describe("Files (listFiles)", () => {
    it("returns a valid ListFilesResponse shape", async () => {
      const result = await client.documents.listFiles({ page_size: 10 });

      expect(typeof result.total).toBe("number");
      expect(result.total).toBeGreaterThanOrEqual(0);
      expect(typeof result.is_approximate).toBe("boolean");
      expect(result.page).toBe(1);
      expect(result.page_size).toBe(10);
      expect(Array.isArray(result.files)).toBe(true);
      // after_key is null on a single page or a cursor dict on multi-page
      expect(result.after_key === null || typeof result.after_key === "object").toBe(true);
    });

    it("each FileRecord contains fields required for knowledge filter construction", async () => {
      // Ingest a known file so there is at least one record
      const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "sdk-lf-"));
      const fname = `lf_test_${Date.now()}.md`;
      const fpath = path.join(tmpDir, fname);
      fs.writeFileSync(fpath, "# List Files Test\n\nUnique content about silver foxes.\n");
      await client.documents.ingest({ filePath: fpath });

      try {
        const result = await client.documents.listFiles({ search: fname });
        const match = result.files.find((r) => r.filename === fname);
        expect(match).toBeDefined();

        const f = match!;
        // Core identity
        expect(typeof f.filename).toBe("string");
        expect(f.filename.length).toBeGreaterThan(0);
        expect(typeof f.document_id).toBe("string");
        // Knowledge-filter fields
        expect(typeof f.connector_type).toBe("string");
        expect(typeof f.mimetype).toBe("string");
        expect(typeof f.owner).toBe("string");
        // Pagination / metadata
        expect(typeof f.chunk_count).toBe("number");
        expect(f.chunk_count).toBeGreaterThanOrEqual(0);
        expect(typeof f.file_size).toBe("number");
        expect(typeof f.indexed_time).toBe("string");
        // ACL fields
        expect(Array.isArray(f.allowed_users)).toBe(true);
        expect(Array.isArray(f.allowed_groups)).toBe(true);
        expect(Array.isArray(f.allowed_principal_labels)).toBe(true);
      } finally {
        await client.documents.delete(fname);
      }
    }, 120_000);

    it("cursor pagination returns non-overlapping pages", async () => {
      const page1 = await client.documents.listFiles({ page_size: 1 });
      expect(page1.files.length).toBeLessThanOrEqual(1);

      if (page1.after_key !== null && page1.total > 1) {
        const page2 = await client.documents.listFiles({
          page_size: 1,
          after_key: JSON.stringify(page1.after_key),
        });
        const p1Names = new Set(page1.files.map((f) => f.filename));
        const p2Names = new Set(page2.files.map((f) => f.filename));
        for (const n of p2Names) {
          expect(p1Names.has(n)).toBe(false);
        }
      }
    });

    it("list → create filter workflow produces a usable filter", async () => {
      const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "sdk-lf-wf-"));
      const fname = `lf_wf_${Date.now()}.md`;
      const fpath = path.join(tmpDir, fname);
      fs.writeFileSync(fpath, "# Workflow Test\n\nContent about crimson crabs.\n");
      await client.documents.ingest({ filePath: fpath });
      let filterId: string | undefined;

      try {
        const page = await client.documents.listFiles({ search: fname });
        const match = page.files.find((f) => f.filename === fname);
        expect(match).toBeDefined();

        const createResult = await client.knowledgeFilters.create({
          name: `TS list-files workflow ${Date.now()}`,
          queryData: {
            filters: {
              data_sources: [match!.filename],
              document_types: ["*"],
              owners: ["*"],
              connector_types: ["*"],
            },
            limit: 10,
            scoreThreshold: 0,
          },
        });
        expect(createResult.success).toBe(true);
        expect(createResult.id).toBeDefined();
        filterId = createResult.id!;
      } finally {
        if (filterId) await client.knowledgeFilters.delete(filterId);
        await client.documents.delete(fname);
      }
    }, 120_000);
  });
});