@digital-science-dsl/dimensions-analytics-mcp 0.5.3

package/test/dsl/integration/client.integration.test.ts

@@ -0,0 +1,294 @@
+/**
+ * Integration tests for DimensionsClient structured search via QueryBuilder.
+ * @module test/integration/client.integration
+ */
+
+import { beforeAll, beforeEach, describe, expect, it } from "vitest";
+import { DimensionsClient, QueryBuilder, ValidationError } from "../../../../src/dsl/index.js";
+import { runSearch } from "./search-helpers.js";
+import { loadTestConfig } from "./test-config.js";
+
+const config = loadTestConfig();
+
+const INTEGRATION_TEST_TIMEOUT = 30_000;
+const RATE_LIMIT_AWARE_TIMEOUT = 90_000;
+
+describe.skipIf(!config)("DimensionsClient Integration", () => {
+  let client: DimensionsClient;
+
+  beforeAll(() => {
+    if (!config) {
+      throw new Error("Config is required - this should not happen due to skipIf");
+    }
+
+    client = new DimensionsClient({
+      apiKey: config.apiKey,
+      ...(config.baseUrl && { baseUrl: config.baseUrl }),
+      rateLimitPerMinute: 30,
+    });
+  });
+
+  beforeEach(() => {
+    client.resetRateLimiter();
+  });
+
+  describe("publications search", () => {
+    it("searches with basic query", async () => {
+      const result = await runSearch(client, "publications", (qb) =>
+        qb.for("CRISPR gene editing").limit(5),
+      );
+
+      expect(result.data.length).toBeGreaterThan(0);
+      expect(result.data.length).toBeLessThanOrEqual(5);
+      expect(result.totalCount).toBeGreaterThan(0);
+      expect(result.data[0]).toHaveProperty("id");
+      expect(result.data[0]).toHaveProperty("title");
+    });
+
+    it("searches with specific fields", async () => {
+      const result = await runSearch(client, "publications", (qb) =>
+        qb.for("machine learning").limit(3).fields(["id", "title", "doi", "year"]),
+      );
+
+      expect(result.data.length).toBeGreaterThan(0);
+      expect(result.data[0]?.id).toBeDefined();
+      expect(result.data[0]?.title).toBeDefined();
+    });
+
+    it("searches with year filter", async () => {
+      const result = await runSearch(client, "publications", (qb) =>
+        qb
+          .for("artificial intelligence")
+          .where("year", ">=", 2023)
+          .where("year", "<=", 2024)
+          .limit(5),
+      );
+
+      expect(result.data.length).toBeGreaterThan(0);
+      for (const pub of result.data) {
+        const year = (pub as { year?: number }).year;
+        if (year !== undefined) {
+          expect(year).toBeGreaterThanOrEqual(2023);
+          expect(year).toBeLessThanOrEqual(2024);
+        }
+      }
+    });
+
+    it("supports pagination with skip", async () => {
+      const firstPage = await runSearch(client, "publications", (qb) =>
+        qb.for("neural networks").limit(3).skip(0),
+      );
+      const secondPage = await runSearch(client, "publications", (qb) =>
+        qb.for("neural networks").limit(3).skip(3),
+      );
+
+      expect(firstPage.data.length).toBe(3);
+      expect(secondPage.data.length).toBe(3);
+      const firstIds = firstPage.data.map((p) => (p as { id: string }).id);
+      const secondIds = secondPage.data.map((p) => (p as { id: string }).id);
+      expect(firstIds).not.toEqual(secondIds);
+    });
+
+    it("filters by publication type", async () => {
+      const result = await runSearch(client, "publications", (qb) =>
+        qb.for("cancer").where("type", "=", "article").limit(5),
+      );
+
+      expect(result.data.length).toBeGreaterThan(0);
+      for (const pub of result.data) {
+        const type = (pub as { type?: string }).type;
+        if (type) expect(type).toBe("article");
+      }
+    });
+  });
+
+  describe("grants search", () => {
+    it("searches grants with basic query", async () => {
+      const result = await runSearch(client, "grants", (qb) => qb.for("cancer research").limit(5));
+
+      expect(result.data.length).toBeGreaterThan(0);
+      expect(result.totalCount).toBeGreaterThan(0);
+      expect(result.data[0]).toHaveProperty("id");
+      expect(result.data[0]).toHaveProperty("title");
+    });
+
+    it("filters by start year and funder", async () => {
+      const result = await runSearch(client, "grants", (qb) =>
+        qb
+          .for("research")
+          .where("start_year", ">=", 2020)
+          .where("start_year", "<=", 2024)
+          .where("funder_org_name", "=", "National Institutes of Health")
+          .limit(5),
+      );
+
+      expect(result.data.length).toBeGreaterThanOrEqual(0);
+      expect(result.totalCount).toBeGreaterThanOrEqual(0);
+    });
+  });
+
+  describe("researchers search", () => {
+    it("returns researcher rows", async () => {
+      const result = await runSearch(client, "researchers", (qb) => qb.for("*").limit(5));
+
+      expect(Array.isArray(result.data)).toBe(true);
+      expect(result.totalCount).toBeGreaterThanOrEqual(0);
+    });
+  });
+
+  describe("patents search", () => {
+    it("searches patents with year filter", async () => {
+      const result = await runSearch(client, "patents", (qb) =>
+        qb.for("battery technology").where("year", ">=", 2020).where("year", "<=", 2023).limit(5),
+      );
+
+      expect(result.data.length).toBeGreaterThan(0);
+    });
+  });
+
+  describe("clinical_trials search", () => {
+    it(
+      "searches clinical trials with phase filter",
+      async () => {
+        const result = await runSearch(client, "clinical_trials", (qb) =>
+          qb.for("diabetes").where("phase", "=", "Phase 3").limit(5),
+        );
+
+        expect(result.data.length).toBeGreaterThan(0);
+        expect(result.totalCount).toBeGreaterThan(0);
+      },
+      RATE_LIMIT_AWARE_TIMEOUT,
+    );
+  });
+
+  describe("datasets search", () => {
+    it(
+      "searches datasets with year filter",
+      async () => {
+        const result = await runSearch(client, "datasets", (qb) =>
+          qb.for("climate").where("year", ">=", 2020).where("year", "<=", 2024).limit(5),
+        );
+
+        expect(result.totalCount).toBeGreaterThanOrEqual(0);
+        expect(Array.isArray(result.data)).toBe(true);
+      },
+      RATE_LIMIT_AWARE_TIMEOUT,
+    );
+  });
+
+  describe("organizations search", () => {
+    it(
+      "searches organizations",
+      async () => {
+        const result = await runSearch(client, "organizations", (qb) =>
+          qb.for("university").limit(5),
+        );
+
+        expect(result.data.length).toBeGreaterThan(0);
+        expect(result.data[0]).toHaveProperty("id");
+        expect(result.data[0]).toHaveProperty("name");
+      },
+      RATE_LIMIT_AWARE_TIMEOUT,
+    );
+  });
+
+  describe("policy_documents search", () => {
+    it(
+      "searches policy documents",
+      async () => {
+        const result = await runSearch(client, "policy_documents", (qb) =>
+          qb.for("climate change").limit(5),
+        );
+
+        expect(result.data.length).toBeGreaterThan(0);
+        expect(result.totalCount).toBeGreaterThan(0);
+      },
+      RATE_LIMIT_AWARE_TIMEOUT,
+    );
+  });
+
+  describe("Client behavior", () => {
+    it("tracks rate limit usage", async () => {
+      await runSearch(client, "publications", (qb) => qb.for("test query").limit(1));
+
+      const infoAfter = client.getRateLimitInfo();
+      expect(infoAfter.remaining).toBeLessThan(30);
+      expect(infoAfter.remaining).toBeGreaterThanOrEqual(0);
+    });
+  });
+
+  describe("Client features", () => {
+    it(
+      "invalidates token and re-authenticates",
+      async () => {
+        await runSearch(client, "publications", (qb) => qb.for("test").limit(1));
+        client.invalidateToken();
+        const result = await runSearch(client, "publications", (qb) => qb.for("test").limit(1));
+        expect(result.data).toBeDefined();
+      },
+      RATE_LIMIT_AWARE_TIMEOUT,
+    );
+
+    it(
+      "handles concurrent requests",
+      async () => {
+        const requests = [
+          runSearch(client, "publications", (qb) => qb.for("test1").limit(1)),
+          runSearch(client, "publications", (qb) => qb.for("test2").limit(1)),
+          runSearch(client, "publications", (qb) => qb.for("test3").limit(1)),
+        ];
+
+        const results = await Promise.all(requests);
+        expect(results).toHaveLength(3);
+        for (const result of results) {
+          expect(result.data).toBeDefined();
+        }
+      },
+      RATE_LIMIT_AWARE_TIMEOUT,
+    );
+  });
+
+  describe("Edge cases", () => {
+    it(
+      "handles unicode queries",
+      async () => {
+        const result = await runSearch(client, "publications", (qb) =>
+          qb.for("研究 科学").limit(3),
+        );
+
+        expect(Array.isArray(result.data)).toBe(true);
+        expect(result.totalCount).toBeGreaterThanOrEqual(0);
+      },
+      INTEGRATION_TEST_TIMEOUT,
+    );
+
+    it(
+      "returns totalCount greater than or equal to results length",
+      async () => {
+        const result = await runSearch(client, "publications", (qb) => qb.for("biology").limit(5));
+
+        expect(result.totalCount).toBeGreaterThanOrEqual(result.data.length);
+      },
+      INTEGRATION_TEST_TIMEOUT,
+    );
+  });
+
+  describe("Error handling", () => {
+    it("throws error with invalid API key", async () => {
+      const badClient = new DimensionsClient({
+        apiKey: "invalid-api-key-12345",
+        ...(config!.baseUrl && { baseUrl: config!.baseUrl }),
+      });
+
+      await expect(
+        runSearch(badClient, "publications", (qb) => qb.for("test").limit(1)),
+      ).rejects.toThrow();
+    });
+
+    it("throws ValidationError for negative limit", () => {
+      expect(() => new QueryBuilder().search("publications").for("test").limit(-1).build()).toThrow(
+        ValidationError,
+      );
+    });
+  });
+});

package/test/dsl/integration/facet-api.integration.test.ts

@@ -0,0 +1,276 @@
+/**
+ * Integration tests for Facet API.
+ * Tests facet and aggregation functionality against the real Dimensions API.
+ * @module test/integration/facet-api.integration
+ */
+
+import { beforeAll, describe, expect, it } from "vitest";
+import { DimensionsClient } from "../../../../src/dsl/index.js";
+
+import { loadTestConfig } from "./test-config.js";
+
+const config = loadTestConfig(); // was: process.env.DIMENSIONS_API_KEY
+const TIMEOUT = 30_000;
+
+describe.skipIf(!config)("Facet API Integration", () => {
+  let client: DimensionsClient;
+
+  beforeAll(() => {
+    client = new DimensionsClient({
+      apiKey: config!.apiKey,
+      ...(config!.baseUrl && { baseUrl: config!.baseUrl }),
+      rateLimitPerMinute: 30,
+    });
+  });
+
+  describe("publications facets", () => {
+    it(
+      "returns year facet buckets with valid structure",
+      async () => {
+        const result = await client
+          .publications()
+          .for("CRISPR")
+          .withFacet("year")
+          .executeWithFacets();
+
+        expect(result.facets.year).toBeDefined();
+        expect(result.facets.year.buckets.length).toBeGreaterThan(0);
+        expect(result.facets.year.field).toBe("year");
+
+        // Contract: bucket must have id (number) and count (non-negative integer)
+        for (const bucket of result.facets.year.buckets) {
+          expect(typeof bucket.id).toBe("number");
+          expect(typeof bucket.count).toBe("number");
+          expect(Number.isInteger(bucket.count)).toBe(true);
+          expect(bucket.count).toBeGreaterThanOrEqual(0);
+        }
+      },
+      TIMEOUT,
+    );
+
+    it(
+      "returns year facet with limit",
+      async () => {
+        const result = await client
+          .publications()
+          .for("machine learning")
+          .withFacet("year", { limit: 5 })
+          .executeWithFacets();
+
+        expect(result.facets.year.buckets.length).toBeLessThanOrEqual(5);
+      },
+      TIMEOUT,
+    );
+
+    it(
+      "returns funders facet buckets with valid structure",
+      async () => {
+        const result = await client
+          .publications()
+          .for("cancer research")
+          .withFacet("funders", { limit: 10 })
+          .executeWithFacets();
+
+        expect(result.facets.funders).toBeDefined();
+        expect(result.facets.funders.buckets.length).toBeGreaterThan(0);
+
+        // Contract: entity ref bucket must have id (string), count, and name
+        for (const bucket of result.facets.funders.buckets) {
+          expect(typeof bucket.id).toBe("string");
+          expect(typeof bucket.count).toBe("number");
+          expect(Number.isInteger(bucket.count)).toBe(true);
+          expect(bucket.count).toBeGreaterThanOrEqual(0);
+          // Entity ref buckets have additional metadata
+          expect(bucket).toHaveProperty("name");
+        }
+      },
+      TIMEOUT,
+    );
+
+    it(
+      "returns multiple facets",
+      async () => {
+        const result = await client
+          .publications()
+          .for("genomics")
+          .withFacet("year")
+          .withFacet("type")
+          .executeWithFacets();
+
+        expect(result.facets.year).toBeDefined();
+        expect(result.facets.type).toBeDefined();
+        expect(result.facets.year.buckets.length).toBeGreaterThan(0);
+        expect(result.facets.type.buckets.length).toBeGreaterThan(0);
+      },
+      TIMEOUT,
+    );
+
+    it(
+      "returns aggregated facet with rcr_avg and valid structure",
+      async () => {
+        const result = await client
+          .publications()
+          .for("CRISPR")
+          .withAggregate("funders", ["rcr_avg"], {
+            sortBy: "rcr_avg",
+            sortOrder: "desc",
+            limit: 10,
+          })
+          .executeWithFacets();
+
+        expect(result.facets.funders).toBeDefined();
+        expect(result.facets.funders.buckets.length).toBeGreaterThan(0);
+
+        // Contract: aggregated bucket must have base fields + indicator
+        for (const bucket of result.facets.funders.buckets) {
+          expect(typeof bucket.id).toBe("string");
+          expect(typeof bucket.count).toBe("number");
+          expect(Number.isInteger(bucket.count)).toBe(true);
+          expect(bucket).toHaveProperty("rcr_avg");
+          expect(typeof bucket.rcr_avg).toBe("number");
+        }
+      },
+      TIMEOUT,
+    );
+
+    it(
+      "returns aggregated facet with multiple indicators and valid structure",
+      async () => {
+        const result = await client
+          .publications()
+          .for("machine learning")
+          .withAggregate("research_orgs", ["rcr_avg", "citations_avg"], {
+            sortBy: "citations_avg",
+            sortOrder: "desc",
+            limit: 5,
+          })
+          .executeWithFacets();
+
+        expect(result.facets.research_orgs).toBeDefined();
+        expect(result.facets.research_orgs.buckets.length).toBeGreaterThan(0);
+
+        // Contract: all requested indicators must be present as numbers
+        for (const bucket of result.facets.research_orgs.buckets) {
+          expect(typeof bucket.id).toBe("string");
+          expect(typeof bucket.count).toBe("number");
+          expect(bucket).toHaveProperty("rcr_avg");
+          expect(bucket).toHaveProperty("citations_avg");
+          expect(typeof bucket.rcr_avg).toBe("number");
+          expect(typeof bucket.citations_avg).toBe("number");
+        }
+      },
+      TIMEOUT,
+    );
+
+    it(
+      "combines entities with facets and validates structure",
+      async () => {
+        const result = await client
+          .publications()
+          .for("COVID-19")
+          .fields(["id", "title", "year"])
+          .limit(10)
+          .withFacet("year")
+          .executeWithFacets();
+
+        // Contract: entities must have data array and totalCount
+        expect(result.entities).toBeDefined();
+        expect(Array.isArray(result.entities!.data)).toBe(true);
+        expect(result.entities!.data.length).toBeGreaterThan(0);
+        expect(typeof result.entities!.totalCount).toBe("number");
+        expect(result.entities!.totalCount).toBeGreaterThan(0);
+
+        // Contract: facets must still be valid
+        expect(result.facets.year).toBeDefined();
+        expect(result.facets.year.buckets.length).toBeGreaterThan(0);
+        for (const bucket of result.facets.year.buckets) {
+          expect(typeof bucket.id).toBe("number");
+          expect(typeof bucket.count).toBe("number");
+        }
+      },
+      TIMEOUT,
+    );
+
+    it(
+      "preserves raw response",
+      async () => {
+        const result = await client
+          .publications()
+          .for("CRISPR")
+          .withFacet("year")
+          .executeWithFacets();
+
+        expect(result._raw).toBeDefined();
+        expect(result._raw.year).toBeDefined();
+      },
+      TIMEOUT,
+    );
+  });
+
+  describe("grants facets", () => {
+    it(
+      "returns start_year facet buckets with valid structure",
+      async () => {
+        const result = await client
+          .grants()
+          .for("cancer research")
+          .withFacet("start_year")
+          .executeWithFacets();
+
+        expect(result.facets.start_year).toBeDefined();
+        expect(result.facets.start_year.buckets.length).toBeGreaterThan(0);
+
+        // Contract: year bucket must have numeric id and integer count
+        for (const bucket of result.facets.start_year.buckets) {
+          expect(typeof bucket.id).toBe("number");
+          expect(typeof bucket.count).toBe("number");
+          expect(Number.isInteger(bucket.count)).toBe(true);
+          expect(bucket.count).toBeGreaterThanOrEqual(0);
+        }
+      },
+      TIMEOUT,
+    );
+
+    it(
+      "returns funders with funding aggregation and valid structure",
+      async () => {
+        const result = await client
+          .grants()
+          .for("renewable energy")
+          .withAggregate("funders", ["funding"], {
+            sortBy: "funding",
+            sortOrder: "desc",
+            limit: 10,
+          })
+          .executeWithFacets();
+
+        expect(result.facets.funders).toBeDefined();
+        expect(result.facets.funders.buckets.length).toBeGreaterThan(0);
+
+        // Contract: funding aggregation must be a number
+        for (const bucket of result.facets.funders.buckets) {
+          expect(typeof bucket.id).toBe("string");
+          expect(typeof bucket.count).toBe("number");
+          expect(bucket).toHaveProperty("funding");
+          expect(typeof bucket.funding).toBe("number");
+        }
+      },
+      TIMEOUT,
+    );
+  });
+
+  describe("getDsl with facets", () => {
+    it("returns DSL string without executing", () => {
+      const dsl = client
+        .publications()
+        .for("CRISPR")
+        .withFacet("year")
+        .withAggregate("funders", ["rcr_avg"], { limit: 10 })
+        .getDsl();
+
+      expect(dsl).toContain('search publications for "CRISPR"');
+      expect(dsl).toContain("return year");
+      expect(dsl).toContain("return funders aggregate rcr_avg limit 10");
+    });
+  });
+});