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

package/dist/dsl/client.js

@@ -0,0 +1,433 @@
+/**
+ * Main DimensionsClient class for interacting with the Dimensions API.
+ * Orchestrates authentication, rate limiting, and HTTP communication.
+ * @module client
+ */
+import { createAuthProvider, DimensionsClientConfigSchema, HttpClient, InternalDslClient, RateLimiter, ValidationError, } from "../client/index.js";
+import { ClassifyCommand, ExtractAffiliationsCommand, ExtractConceptsCommand, ExtractGrantsCommand, } from "./commands/functions/index.js";
+import { FluentQueryBuilder } from "./fluent-query-builder.js";
+import { QueryBuilder } from "./query-builder.js";
+/**
+ * Client for interacting with the Dimensions Analytics API.
+ * Handles authentication, rate limiting, and command execution.
+ *
+ * @example
+ * ```typescript
+ * const client = new DimensionsClient({ apiKey: "your-api-key" });
+ *
+ * const result = await client.send(
+ *   client.rawQuery('search publications for "machine learning" return publications limit 10')
+ * );
+ * ```
+ */
+export class DimensionsClient {
+    config;
+    authProvider;
+    httpClient;
+    internalClient;
+    rateLimiter;
+    schemaStore;
+    /**
+     * Creates a new DimensionsClient instance.
+     * @param config - Client configuration
+     * @throws {ValidationError} If configuration is invalid
+     */
+    constructor(config) {
+        // Validate and apply defaults
+        const parseResult = DimensionsClientConfigSchema.safeParse(config);
+        if (!parseResult.success) {
+            throw new ValidationError(`Invalid configuration: ${parseResult.error.message}`, {
+                issues: parseResult.error.issues,
+            });
+        }
+        this.config = parseResult.data;
+        if (this.config.backend === "internal") {
+            const internal = this.config.internal;
+            this.internalClient = new InternalDslClient({
+                config: internal.service,
+                userEmail: internal.userEmail,
+                clientIp: internal.clientIp,
+                timeout: this.config.timeout,
+            });
+            this.rateLimiter = new RateLimiter({
+                maxRequests: 1000,
+                windowMs: 60_000,
+            });
+            return;
+        }
+        this.authProvider = createAuthProvider({
+            type: "jwt",
+            apiKey: this.config.apiKey,
+            authUrl: `${this.config.baseUrl}/api/auth.json`,
+            timeout: this.config.timeout,
+        });
+        this.rateLimiter = new RateLimiter({
+            maxRequests: this.config.rateLimitPerMinute,
+            windowMs: 60_000,
+        });
+        this.httpClient = new HttpClient({
+            baseUrl: this.config.baseUrl,
+            authProvider: this.authProvider,
+            timeout: this.config.timeout,
+            maxRetries: this.config.maxRetries,
+            retryDelay: this.config.retryDelay,
+            rateLimiter: this.rateLimiter,
+        });
+    }
+    async executeDslQuery(dsl, endpoint, options) {
+        if (this.internalClient) {
+            return this.internalClient.query(dsl, options);
+        }
+        const response = await this.httpClient.query(dsl, endpoint, options);
+        return response;
+    }
+    /**
+     * Sends a command to the Dimensions API.
+     * @param command - The command to execute
+     * @returns The transformed response
+     * @throws {ValidationError} If command input is invalid
+     * @throws {AuthenticationError} If authentication fails
+     * @throws {RateLimitError} If rate limit is exceeded
+     * @throws {QuerySyntaxError} If query syntax is invalid
+     * @throws {ServerError} If server error occurs
+     * @throws {NetworkError} If network error occurs
+     * @throws {TimeoutError} If request times out
+     */
+    async send(command) {
+        // Build DSL query
+        const dsl = command.resolveQuery?.() ?? "";
+        const endpoint = command.resolveEndpoint();
+        // Validate DSL before sending if enabled
+        if (dsl && this.config.validateQueries) {
+            this.assertValidDsl(dsl);
+        }
+        // Execute HTTP query (auth and rate limiting are handled by HttpClient)
+        const response = await this.executeDslQuery(dsl, endpoint, undefined);
+        // Transform response if command has a transformer
+        if (command.transformResponse) {
+            return command.transformResponse(response);
+        }
+        // Return raw response if no transformer
+        return response;
+    }
+    /**
+     * Gets current rate limit status.
+     * @returns Rate limit information
+     */
+    getRateLimitInfo() {
+        return {
+            remaining: this.rateLimiter.getRemainingRequests(),
+            resetInMs: this.rateLimiter.getTimeUntilNextSlot(),
+        };
+    }
+    /**
+     * Invalidates the cached authentication token.
+     * Forces a new token to be fetched on the next request.
+     */
+    invalidateToken() {
+        this.authProvider?.invalidate();
+    }
+    /**
+     * Resets the rate limiter, clearing all recorded request timestamps.
+     * Useful for testing or when starting a fresh session.
+     */
+    resetRateLimiter() {
+        this.rateLimiter.reset();
+    }
+    /**
+     * Executes a raw DSL query against the Dimensions API.
+     * Use this for generic/dynamic queries not covered by specific commands.
+     *
+     * @param dsl - The DSL query string to execute
+     * @param options - Optional signal and timeout overrides
+     * @returns The raw API response
+     * @throws {AuthenticationError} If authentication fails
+     * @throws {RateLimitError} If rate limit is exceeded
+     * @throws {QuerySyntaxError} If query syntax is invalid
+     * @throws {ServerError} If server error occurs
+     * @throws {NetworkError} If network error occurs
+     * @throws {TimeoutError} If request times out
+     *
+     * @example
+     * ```typescript
+     * const response = await client.rawQuery(
+     *   'search publications for "CRISPR" return publications[id+title] limit 10'
+     * );
+     * console.log(response.publications);
+     * ```
+     */
+    async rawQuery(dsl, options) {
+        // Validate DSL before sending if enabled
+        if (this.config.validateQueries) {
+            this.assertValidDsl(dsl);
+        }
+        // Execute HTTP query (auth and rate limiting are handled by HttpClient)
+        const response = await this.executeDslQuery(dsl, "/api/dsl/v2", options);
+        return response;
+    }
+    /**
+     * Validates a DSL string and throws {@link ValidationError} if it is invalid.
+     * @param dsl - The DSL query string to validate
+     * @throws {ValidationError} If the DSL fails parsing or semantic validation
+     */
+    assertValidDsl(_dsl) {
+        // Local parser validation removed; Dimensions API validates on execute.
+    }
+    /**
+     * Attaches a loaded describe schema for QueryBuilder entity/index validation.
+     * @param store - Schema from {@link loadSchema} or {@link getOrLoadSchema}
+     */
+    attachSchemaStore(store) {
+        this.schemaStore = store;
+    }
+    /**
+     * Creates a {@link QueryBuilder} validated against the attached schema when present.
+     * @returns New query builder instance
+     */
+    createQueryBuilder() {
+        return new QueryBuilder(this.schemaStore);
+    }
+    // #region Fluent API Entity Entry Points
+    /**
+     * Creates a type-safe fluent query builder for the specified entity.
+     * @param entity - The entity type key
+     * @returns A FluentQueryBuilder typed to the entity
+     */
+    createFluentBuilder(entity) {
+        return new FluentQueryBuilder(this, entity, this.schemaStore);
+    }
+    /**
+     * Creates a fluent query builder for publications.
+     * @returns A FluentQueryBuilder configured for publications
+     *
+     * @example
+     * ```typescript
+     * const result = await client
+     *   .publications()
+     *   .for("machine learning")
+     *   .where("year", ">=", 2020)
+     *   .fields(["id", "title", "doi"])
+     *   .execute();
+     * ```
+     */
+    publications() {
+        return this.createFluentBuilder("publications");
+    }
+    /**
+     * Creates a fluent query builder for grants.
+     * @returns A FluentQueryBuilder configured for grants
+     *
+     * @example
+     * ```typescript
+     * const result = await client
+     *   .grants()
+     *   .for("cancer research")
+     *   .where("funding_usd", ">", 1000000)
+     *   .execute();
+     * ```
+     */
+    grants() {
+        return this.createFluentBuilder("grants");
+    }
+    /**
+     * Creates a fluent query builder for researchers.
+     * @returns A FluentQueryBuilder configured for researchers
+     *
+     * @example
+     * ```typescript
+     * const result = await client
+     *   .researchers()
+     *   .for("smith")
+     *   .whereNotEmpty("orcid_id")
+     *   .execute();
+     * ```
+     */
+    researchers() {
+        return this.createFluentBuilder("researchers");
+    }
+    /**
+     * Creates a fluent query builder for patents.
+     * @returns A FluentQueryBuilder configured for patents
+     *
+     * @example
+     * ```typescript
+     * const result = await client
+     *   .patents()
+     *   .for("battery technology")
+     *   .where("year", ">=", 2020)
+     *   .execute();
+     * ```
+     */
+    patents() {
+        return this.createFluentBuilder("patents");
+    }
+    /**
+     * Creates a fluent query builder for clinical trials.
+     * @returns A FluentQueryBuilder configured for clinical_trials
+     *
+     * @example
+     * ```typescript
+     * const result = await client
+     *   .clinicalTrials()
+     *   .for("diabetes")
+     *   .where("phase", "=", "Phase 3")
+     *   .execute();
+     * ```
+     */
+    clinicalTrials() {
+        return this.createFluentBuilder("clinical_trials");
+    }
+    /**
+     * Creates a fluent query builder for datasets.
+     * @returns A FluentQueryBuilder configured for datasets
+     *
+     * @example
+     * ```typescript
+     * const result = await client
+     *   .datasets()
+     *   .for("genomics")
+     *   .where("year", ">=", 2020)
+     *   .execute();
+     * ```
+     */
+    datasets() {
+        return this.createFluentBuilder("datasets");
+    }
+    /**
+     * Creates a fluent query builder for policy documents.
+     * @returns A FluentQueryBuilder configured for policy_documents
+     *
+     * @example
+     * ```typescript
+     * const result = await client
+     *   .policyDocuments()
+     *   .for("climate change")
+     *   .execute();
+     * ```
+     */
+    policyDocuments() {
+        return this.createFluentBuilder("policy_documents");
+    }
+    /**
+     * Creates a fluent query builder for organizations.
+     * @returns A FluentQueryBuilder configured for organizations
+     *
+     * @example
+     * ```typescript
+     * const result = await client
+     *   .organizations()
+     *   .for("stanford")
+     *   .execute();
+     * ```
+     */
+    organizations() {
+        return this.createFluentBuilder("organizations");
+    }
+    // #endregion
+    // #region Special Function Methods
+    /**
+     * Classifies text using a specified Dimensions classification system.
+     * Supports FOR, SDG, RCDC, and other research classification taxonomies.
+     *
+     * @template S - The classification system type
+     * @param options - Classification options including title, abstract, and system
+     * @returns Classification codes with their names
+     * @throws {ValidationError} If input validation fails
+     * @throws {AuthenticationError} If authentication fails
+     * @throws {QuerySyntaxError} If query syntax is invalid
+     *
+     * @example
+     * ```typescript
+     * const result = await client.classify({
+     *   title: "Burnout and intentions to quit the nursing profession",
+     *   abstract: "BACKGROUND: Burnout is an occupational disease...",
+     *   system: "FOR"
+     * });
+     * console.log(result.FOR); // [{ id: "1117", name: "Public Health..." }]
+     * ```
+     */
+    async classify(options) {
+        return this.send(new ClassifyCommand(options));
+    }
+    /**
+     * Extracts concepts from text using Dimensions natural language processing.
+     *
+     * @template WithScores - Whether to include relevance scores
+     * @param text - Text to extract concepts from
+     * @param options - Optional settings including returnScores
+     * @returns Array of concepts, optionally with relevance scores
+     * @throws {ValidationError} If input validation fails
+     * @throws {AuthenticationError} If authentication fails
+     * @throws {QuerySyntaxError} If query syntax is invalid
+     *
+     * @example
+     * ```typescript
+     * // Simple extraction
+     * const concepts = await client.extractConcepts(
+     *   "Machine learning algorithms for drug discovery"
+     * );
+     * console.log(concepts.extracted_concepts); // ["machine learning", "drug discovery", ...]
+     *
+     * // With relevance scores
+     * const conceptsWithScores = await client.extractConcepts(
+     *   "Machine learning algorithms for drug discovery",
+     *   { returnScores: true }
+     * );
+     * console.log(conceptsWithScores.extracted_concepts);
+     * // [{ concept: "machine learning", relevance: 0.95 }, ...]
+     * ```
+     */
+    async extractConcepts(text, options) {
+        return this.send(new ExtractConceptsCommand({
+            text,
+            returnScores: (options?.returnScores ?? false),
+        }));
+    }
+    /**
+     * Extracts and resolves organization affiliations using Dimensions entity resolution.
+     * Takes freetext or structured affiliation data and returns matched organizations.
+     *
+     * @param affiliations - Array of affiliation inputs to resolve
+     * @returns Array of resolved organization matches with confidence scores
+     * @throws {ValidationError} If input validation fails
+     * @throws {AuthenticationError} If authentication fails
+     * @throws {QuerySyntaxError} If query syntax is invalid
+     *
+     * @example
+     * ```typescript
+     * const result = await client.extractAffiliations([
+     *   { affiliation: "University of Oxford, UK" },
+     *   { name: "Stanford", city: "Stanford", country: "USA" }
+     * ]);
+     * console.log(result.extracted_affiliations);
+     * // [{ id: "grid.4991.5", name: "University of Oxford", score: 0.95 }, ...]
+     * ```
+     */
+    async extractAffiliations(affiliations) {
+        return this.send(new ExtractAffiliationsCommand({ affiliations }));
+    }
+    /**
+     * Resolves a grant number to a Dimensions grant ID.
+     * Takes a grant number and optional funder information to find the matching grant.
+     *
+     * @param options - Grant lookup parameters
+     * @returns Resolved grant ID, or null if no match found
+     * @throws {ValidationError} If input validation fails
+     * @throws {AuthenticationError} If authentication fails
+     * @throws {QuerySyntaxError} If query syntax is invalid
+     *
+     * @example
+     * ```typescript
+     * const result = await client.extractGrants({
+     *   grantNumber: "R01HL117329",
+     *   fundref: "100000050"
+     * });
+     * console.log(result.grant_id);
+     * // "grant.2544064"
+     * ```
+     */
+    async extractGrants(options) {
+        return this.send(new ExtractGrantsCommand(options));
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/dsl/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/dsl/client.ts"],"names":[],"mappings":"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"}

package/dist/dsl/commands/apply-filters.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Shared helper for applying extended where filters to a QueryBuilder.
+ * @module commands/apply-filters
+ */
+import type { QueryBuilder } from "../query-builder.js";
+import type { ExtendedWhereFilterInput } from "./facet/schemas.js";
+/**
+ * Applies an array of extended where filters to a QueryBuilder instance.
+ * Dispatches to the appropriate QueryBuilder method based on the filter operator.
+ *
+ * @param builder - QueryBuilder instance to apply filters to
+ * @param filters - Array of extended where filters
+ */
+export declare function applyFilters(builder: QueryBuilder, filters: readonly ExtendedWhereFilterInput[]): void;
+//# sourceMappingURL=apply-filters.d.ts.map

package/dist/dsl/commands/apply-filters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply-filters.d.ts","sourceRoot":"","sources":["../../../src/dsl/commands/apply-filters.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,oBAAoB,CAAC;AAEnE;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,YAAY,EACrB,OAAO,EAAE,SAAS,wBAAwB,EAAE,GAC3C,IAAI,CAgBN"}

package/dist/dsl/commands/apply-filters.js

@@ -0,0 +1,29 @@
+/**
+ * Shared helper for applying extended where filters to a QueryBuilder.
+ * @module commands/apply-filters
+ */
+/**
+ * Applies an array of extended where filters to a QueryBuilder instance.
+ * Dispatches to the appropriate QueryBuilder method based on the filter operator.
+ *
+ * @param builder - QueryBuilder instance to apply filters to
+ * @param filters - Array of extended where filters
+ */
+export function applyFilters(builder, filters) {
+    for (const f of filters) {
+        switch (f.operator) {
+            case "is_empty":
+                builder.whereEmpty(f.field);
+                break;
+            case "is_not_empty":
+                builder.whereNotEmpty(f.field);
+                break;
+            case "in":
+                builder.whereIn(f.field, f.value);
+                break;
+            default:
+                builder.where(f.field, f.operator, f.value);
+        }
+    }
+}
+//# sourceMappingURL=apply-filters.js.map

package/dist/dsl/commands/apply-filters.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply-filters.js","sourceRoot":"","sources":["../../../src/dsl/commands/apply-filters.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAC1B,OAAqB,EACrB,OAA4C;IAE5C,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;QACxB,QAAQ,CAAC,CAAC,QAAQ,EAAE,CAAC;YACnB,KAAK,UAAU;gBACb,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;gBAC5B,MAAM;YACR,KAAK,cAAc;gBACjB,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;gBAC/B,MAAM;YACR,KAAK,IAAI;gBACP,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC;gBAClC,MAAM;YACR;gBACE,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC;QAChD,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/dsl/commands/facet/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Facet-related schemas shared by QueryBuilder and MCP tools.
+ * @module commands/facet
+ */
+export { EntitySchema, type ExtendedWhereFilterInput, ExtendedWhereFilterSchema, type WhereFilterInput, WhereFilterSchema, } from "./schemas.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/dsl/commands/facet/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/dsl/commands/facet/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACL,YAAY,EACZ,KAAK,wBAAwB,EAC7B,yBAAyB,EACzB,KAAK,gBAAgB,EACrB,iBAAiB,GAClB,MAAM,cAAc,CAAC"}

package/dist/dsl/commands/facet/index.js

@@ -0,0 +1,6 @@
+/**
+ * Facet-related schemas shared by QueryBuilder and MCP tools.
+ * @module commands/facet
+ */
+export { EntitySchema, ExtendedWhereFilterSchema, WhereFilterSchema, } from "./schemas.js";
+//# sourceMappingURL=index.js.map

package/dist/dsl/commands/facet/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/dsl/commands/facet/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACL,YAAY,EAEZ,yBAAyB,EAEzB,iBAAiB,GAClB,MAAM,cAAc,CAAC"}

package/dist/dsl/commands/facet/schemas.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Shared Zod schemas for facet and aggregate commands.
+ * @module commands/facet/schemas
+ */
+import { z } from "zod";
+/**
+ * Zod schema for the entity type field, derived from the core VALID_ENTITIES constant.
+ */
+export declare const EntitySchema: z.ZodEnum<{
+    [x: string]: string;
+}>;
+/**
+ * Schema for where clause filters used in facet/aggregate commands.
+ * Supports basic comparison operators for field-level filtering.
+ */
+export declare const WhereFilterSchema: z.ZodObject<{
+    field: z.ZodString;
+    operator: z.ZodEnum<{
+        "=": "=";
+        "!=": "!=";
+        "<": "<";
+        ">": ">";
+        "<=": "<=";
+        ">=": ">=";
+    }>;
+    value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>;
+}, z.core.$strip>;
+/**
+ * Input type for a where clause filter.
+ */
+export type WhereFilterInput = z.infer<typeof WhereFilterSchema>;
+/**
+ * Extended where filter schema supporting all DSL filter operators.
+ * Covers scalar comparisons, set membership (in), and emptiness checks (is_empty/is_not_empty).
+ *
+ * Uses a discriminated union on `operator` for precise type narrowing.
+ */
+export declare const ExtendedWhereFilterSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    field: z.ZodString;
+    operator: z.ZodEnum<{
+        "=": "=";
+        "!=": "!=";
+        "<": "<";
+        ">": ">";
+        "<=": "<=";
+        ">=": ">=";
+    }>;
+    value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>;
+}, z.core.$strip>, z.ZodObject<{
+    field: z.ZodString;
+    operator: z.ZodLiteral<"in">;
+    value: z.ZodUnion<readonly [z.ZodPipe<z.ZodString, z.ZodTransform<string[], string>>, z.ZodPipe<z.ZodNumber, z.ZodTransform<number[], number>>, z.ZodArray<z.ZodString>, z.ZodArray<z.ZodNumber>]>;
+}, z.core.$strip>, z.ZodObject<{
+    field: z.ZodString;
+    operator: z.ZodLiteral<"is_empty">;
+}, z.core.$strip>, z.ZodObject<{
+    field: z.ZodString;
+    operator: z.ZodLiteral<"is_not_empty">;
+}, z.core.$strip>], "operator">;
+/**
+ * Input type for an extended where filter (supports in/is_empty/is_not_empty).
+ */
+export type ExtendedWhereFilterInput = z.infer<typeof ExtendedWhereFilterSchema>;
+/**
+ * Validates that a raw API response is a non-null object.
+ * @param response - The raw API response
+ * @returns The response as a record
+ * @throws {ValidationError} If response is not a non-null object
+ */
+export declare function assertObjectResponse(response: unknown): Record<string, unknown>;
+//# sourceMappingURL=schemas.d.ts.map

package/dist/dsl/commands/facet/schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../../../../src/dsl/commands/facet/schemas.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB;;GAEG;AACH,eAAO,MAAM,YAAY;;EAA6D,CAAC;AAEvF;;;GAGG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;;;;iBAO5B,CAAC;AAEH;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAyCjE;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;+BAKpC,CAAC;AAEH;;GAEG;AACH,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAEjF;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAK/E"}

package/dist/dsl/commands/facet/schemas.js

@@ -0,0 +1,84 @@
+/**
+ * Shared Zod schemas for facet and aggregate commands.
+ * @module commands/facet/schemas
+ */
+import { z } from "zod";
+import { ValidationError } from "../../../client/index.js";
+import { VALID_ENTITIES } from "../../types/vocabulary.js";
+/**
+ * Zod schema for the entity type field, derived from the core VALID_ENTITIES constant.
+ */
+export const EntitySchema = z.enum(VALID_ENTITIES);
+/**
+ * Schema for where clause filters used in facet/aggregate commands.
+ * Supports basic comparison operators for field-level filtering.
+ */
+export const WhereFilterSchema = z.object({
+    /** Field name to filter on */
+    field: z.string().min(1),
+    /** Comparison operator */
+    operator: z.enum(["=", "!=", ">", "<", ">=", "<="]),
+    /** Value to compare against */
+    value: z.union([z.string(), z.number(), z.boolean()]),
+});
+/**
+ * Schema for scalar comparison filters (=, !=, >, <, >=, <=).
+ */
+const ScalarFilterSchema = z.object({
+    /** Field name to filter on */
+    field: z.string().min(1),
+    /** Scalar comparison operator */
+    operator: z.enum(["=", "!=", ">", "<", ">=", "<="]),
+    /** Value to compare against */
+    value: z.union([z.string(), z.number(), z.boolean()]),
+});
+/**
+ * Schema for set membership filters (in).
+ */
+const InFilterSchema = z.object({
+    /** Field name to filter on */
+    field: z.string().min(1),
+    /** Set membership operator */
+    operator: z.literal("in"),
+    /** Values to match against (scalar is coerced to single-element array) */
+    value: z.union([
+        z.string().transform((v) => [v]),
+        z.number().transform((v) => [v]),
+        z.array(z.string()).min(1),
+        z.array(z.number()).min(1),
+    ]),
+});
+/**
+ * Schema for emptiness check filters (is_empty, is_not_empty).
+ */
+const EmptinessFilterSchema = z.object({
+    /** Field name to filter on */
+    field: z.string().min(1),
+    /** Emptiness check operator */
+    operator: z.enum(["is_empty", "is_not_empty"]),
+});
+/**
+ * Extended where filter schema supporting all DSL filter operators.
+ * Covers scalar comparisons, set membership (in), and emptiness checks (is_empty/is_not_empty).
+ *
+ * Uses a discriminated union on `operator` for precise type narrowing.
+ */
+export const ExtendedWhereFilterSchema = z.discriminatedUnion("operator", [
+    ScalarFilterSchema,
+    InFilterSchema,
+    EmptinessFilterSchema.extend({ operator: z.literal("is_empty") }),
+    EmptinessFilterSchema.extend({ operator: z.literal("is_not_empty") }),
+]);
+/**
+ * Validates that a raw API response is a non-null object.
+ * @param response - The raw API response
+ * @returns The response as a record
+ * @throws {ValidationError} If response is not a non-null object
+ */
+export function assertObjectResponse(response) {
+    if (response == null || typeof response !== "object" || Array.isArray(response)) {
+        throw new ValidationError("Expected object response from API");
+    }
+    return response;
+}
+//# sourceMappingURL=schemas.js.map