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

package/dist/dsl/schema/summary.js

@@ -0,0 +1,61 @@
+/**
+ * Compact schema summary for cold-start and agent discovery.
+ * @module schema/summary
+ */
+import { SCHEMA_LIMITS } from "./store.js";
+/** MCP resource URIs for drilling into the full schema. */
+export const SCHEMA_RESOURCE_URIS = {
+    full: "dimensions://schema",
+    summary: "dimensions://schema/summary",
+    version: "dimensions://schema/version",
+    limits: "dimensions://schema/limits",
+    policy: "dimensions://schema/policy",
+    fields: "dimensions://fields/{entityType}",
+    source: "dimensions://schema/sources/{sourceName}",
+    entity: "dimensions://schema/entities/{entityName}",
+    examples: "dimensions://examples",
+    examplesBySource: "dimensions://examples/{source}",
+};
+/**
+ * Builds a compact schema summary from a loaded {@link SchemaStore}.
+ * @param store - Loaded schema store
+ * @returns Summary payload for tools and resources
+ */
+export function buildSchemaSummary(store) {
+    const sources = {};
+    for (const name of store.sourceNames()) {
+        const fieldsets = store.fieldsets(name);
+        sources[name] = {
+            filterableFieldCount: store.filterableFields(name).length,
+            facetFieldCount: store.facetFields(name).length,
+            searchIndexCount: store.searchIndexes(name).length,
+            metricCount: store.metrics(name).length,
+            fieldsetNames: Object.keys(fieldsets).sort(),
+        };
+    }
+    const stats = store.stats();
+    const staleNote = store.stale
+        ? " (stale cache — call refresh_schema when the API is reachable)"
+        : "";
+    return {
+        version: store.version,
+        loadedAt: store.loadedAt.toISOString(),
+        cachedAt: store.cachedAt?.toISOString(),
+        stale: store.stale,
+        loadSource: store.loadSource,
+        limits: SCHEMA_LIMITS,
+        stats: {
+            sourceCount: stats.sourceCount,
+            entityCount: stats.entityCount,
+            structuredEntityTypes: store.structuredEntityTypes(),
+        },
+        sources,
+        entities: store.entityNames(),
+        resources: SCHEMA_RESOURCE_URIS,
+        hint: `Use dimensions://fields/{entityType} for filterable fields and aliases. ` +
+            `Read dimensions://schema/policy before large paginated pulls. ` +
+            `Use dimensions://schema/sources/{name} or describe_schema with source/entity for detail. ` +
+            `Full raw describe: describe_schema with full=true or dimensions://schema.${staleNote}`,
+    };
+}
+//# sourceMappingURL=summary.js.map

package/dist/dsl/schema/summary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"summary.js","sourceRoot":"","sources":["../../../src/dsl/schema/summary.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,aAAa,EAAoB,MAAM,YAAY,CAAC;AAE7D,2DAA2D;AAC3D,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,IAAI,EAAE,qBAAqB;IAC3B,OAAO,EAAE,6BAA6B;IACtC,OAAO,EAAE,6BAA6B;IACtC,MAAM,EAAE,4BAA4B;IACpC,MAAM,EAAE,4BAA4B;IACpC,MAAM,EAAE,kCAAkC;IAC1C,MAAM,EAAE,0CAA0C;IAClD,MAAM,EAAE,2CAA2C;IACnD,QAAQ,EAAE,uBAAuB;IACjC,gBAAgB,EAAE,gCAAgC;CAC1C,CAAC;AA8BX;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAkB;IACnD,MAAM,OAAO,GAAwC,EAAE,CAAC;IACxD,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,WAAW,EAAE,EAAE,CAAC;QACvC,MAAM,SAAS,GAAG,KAAK,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;QACxC,OAAO,CAAC,IAAI,CAAC,GAAG;YACd,oBAAoB,EAAE,KAAK,CAAC,gBAAgB,CAAC,IAAI,CAAC,CAAC,MAAM;YACzD,eAAe,EAAE,KAAK,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,MAAM;YAC/C,gBAAgB,EAAE,KAAK,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC,MAAM;YAClD,WAAW,EAAE,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,MAAM;YACvC,aAAa,EAAE,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,IAAI,EAAE;SAC7C,CAAC;IACJ,CAAC;IAED,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,EAAE,CAAC;IAC5B,MAAM,SAAS,GAAG,KAAK,CAAC,KAAK;QAC3B,CAAC,CAAC,gEAAgE;QAClE,CAAC,CAAC,EAAE,CAAC;IAEP,OAAO;QACL,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,QAAQ,EAAE,KAAK,CAAC,QAAQ,CAAC,WAAW,EAAE;QACtC,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,WAAW,EAAE;QACvC,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,UAAU,EAAE,KAAK,CAAC,UAAU;QAC5B,MAAM,EAAE,aAAa;QACrB,KAAK,EAAE;YACL,WAAW,EAAE,KAAK,CAAC,WAAW;YAC9B,WAAW,EAAE,KAAK,CAAC,WAAW;YAC9B,qBAAqB,EAAE,KAAK,CAAC,qBAAqB,EAAE;SACrD;QACD,OAAO;QACP,QAAQ,EAAE,KAAK,CAAC,WAAW,EAAE;QAC7B,SAAS,EAAE,oBAAoB;QAC/B,IAAI,EACF,0EAA0E;YAC1E,gEAAgE;YAChE,2FAA2F;YAC3F,4EAA4E,SAAS,EAAE;KAC1F,CAAC;AACJ,CAAC"}

package/dist/dsl/schema/types.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Types for Dimensions `describe` API responses.
+ * @module schema/types
+ */
+/** Field metadata from `describe schema` / `describe source`. */
+export type DescribeField = {
+    readonly type: string;
+    readonly description?: string;
+    readonly long_description?: string;
+    readonly is_entity?: boolean;
+    readonly is_filter?: boolean;
+    readonly is_facet?: boolean;
+    readonly is_multivalue?: boolean;
+};
+/** Per-source schema slice from `describe schema`. */
+export type SourceDescribe = {
+    readonly fields: Readonly<Record<string, DescribeField>>;
+    readonly fieldsets?: Readonly<Record<string, readonly string[]>>;
+    readonly metrics?: readonly string[];
+    readonly search_fields?: readonly string[];
+};
+/** Auxiliary entity schema from `describe schema`. */
+export type EntityDescribe = {
+    readonly fields: Readonly<Record<string, DescribeField>>;
+};
+/** Full response from `describe schema`. */
+export type DescribeSchemaResponse = {
+    readonly sources: Readonly<Record<string, SourceDescribe>>;
+    readonly entities: Readonly<Record<string, EntityDescribe>>;
+};
+/** Response from `describe version`. */
+export type DescribeVersionResponse = {
+    readonly version?: string;
+    readonly release?: string;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/dsl/schema/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/dsl/schema/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,iEAAiE;AACjE,MAAM,MAAM,aAAa,GAAG;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;CAClC,CAAC;AAEF,sDAAsD;AACtD,MAAM,MAAM,cAAc,GAAG;IAC3B,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC;IACzD,QAAQ,CAAC,SAAS,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC,CAAC;IACjE,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC5C,CAAC;AAEF,sDAAsD;AACtD,MAAM,MAAM,cAAc,GAAG;IAC3B,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC;CAC1D,CAAC;AAEF,4CAA4C;AAC5C,MAAM,MAAM,sBAAsB,GAAG;IACnC,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC,CAAC;IAC3D,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC,CAAC;CAC7D,CAAC;AAEF,wCAAwC;AACxC,MAAM,MAAM,uBAAuB,GAAG;IACpC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B,CAAC"}

package/dist/dsl/schema/types.js

@@ -0,0 +1,6 @@
+/**
+ * Types for Dimensions `describe` API responses.
+ * @module schema/types
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/dsl/schema/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/dsl/schema/types.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/dist/dsl/schema/validation.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Runtime validation helpers using {@link SchemaStore} when available.
+ * @module schema/validation
+ */
+import type { SchemaStore } from "./store.js";
+/**
+ * Validates a Dimensions source/entity name.
+ * @param schemaStore - Optional loaded describe schema
+ * @param entity - Source name (e.g. `publications`)
+ * @throws {ValidationError} When the source is unknown
+ */
+export declare function assertValidEntity(schemaStore: SchemaStore | undefined, entity: string): void;
+/**
+ * Validates a search index for the current source.
+ * @param schemaStore - Optional loaded describe schema
+ * @param entity - Active source from {@link QueryBuilder.search}, if set
+ * @param index - Search index name
+ * @throws {ValidationError} When the index is unknown
+ */
+export declare function assertValidSearchIndex(schemaStore: SchemaStore | undefined, entity: string | null, index: string): void;
+//# sourceMappingURL=validation.d.ts.map

package/dist/dsl/schema/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../../src/dsl/schema/validation.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,WAAW,GAAG,SAAS,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAa5F;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,WAAW,EAAE,WAAW,GAAG,SAAS,EACpC,MAAM,EAAE,MAAM,GAAG,IAAI,EACrB,KAAK,EAAE,MAAM,GACZ,IAAI,CAaN"}

package/dist/dsl/schema/validation.js

@@ -0,0 +1,44 @@
+/**
+ * Runtime validation helpers using {@link SchemaStore} when available.
+ * @module schema/validation
+ */
+import { ValidationError } from "../../client/index.js";
+import { VALID_ENTITIES, VALID_INDEXES } from "../types/vocabulary.js";
+/**
+ * Validates a Dimensions source/entity name.
+ * @param schemaStore - Optional loaded describe schema
+ * @param entity - Source name (e.g. `publications`)
+ * @throws {ValidationError} When the source is unknown
+ */
+export function assertValidEntity(schemaStore, entity) {
+    if (schemaStore) {
+        if (!schemaStore.getSource(entity)) {
+            const known = schemaStore.sourceNames().join(", ");
+            throw new ValidationError(`Unknown source: ${entity}${known ? `. Known sources: ${known}` : ""}`);
+        }
+        return;
+    }
+    if (!VALID_ENTITIES.includes(entity)) {
+        throw new ValidationError(`Invalid entity type: ${entity}`);
+    }
+}
+/**
+ * Validates a search index for the current source.
+ * @param schemaStore - Optional loaded describe schema
+ * @param entity - Active source from {@link QueryBuilder.search}, if set
+ * @param index - Search index name
+ * @throws {ValidationError} When the index is unknown
+ */
+export function assertValidSearchIndex(schemaStore, entity, index) {
+    if (schemaStore && entity) {
+        const indexes = schemaStore.searchIndexes(entity);
+        if (indexes.length > 0 && !indexes.includes(index)) {
+            throw new ValidationError(`Invalid search index "${index}" for ${entity}. Valid indexes: ${indexes.join(", ")}`);
+        }
+        return;
+    }
+    if (!VALID_INDEXES.includes(index)) {
+        throw new ValidationError(`Invalid search index: ${index}`);
+    }
+}
+//# sourceMappingURL=validation.js.map

package/dist/dsl/schema/validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.js","sourceRoot":"","sources":["../../../src/dsl/schema/validation.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAExD,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAGvE;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,WAAoC,EAAE,MAAc;IACpF,IAAI,WAAW,EAAE,CAAC;QAChB,IAAI,CAAC,WAAW,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC;YACnC,MAAM,KAAK,GAAG,WAAW,CAAC,WAAW,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACnD,MAAM,IAAI,eAAe,CACvB,mBAAmB,MAAM,GAAG,KAAK,CAAC,CAAC,CAAC,oBAAoB,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CACvE,CAAC;QACJ,CAAC;QACD,OAAO;IACT,CAAC;IACD,IAAI,CAAC,cAAc,CAAC,QAAQ,CAAC,MAAoB,CAAC,EAAE,CAAC;QACnD,MAAM,IAAI,eAAe,CAAC,wBAAwB,MAAM,EAAE,CAAC,CAAC;IAC9D,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,sBAAsB,CACpC,WAAoC,EACpC,MAAqB,EACrB,KAAa;IAEb,IAAI,WAAW,IAAI,MAAM,EAAE,CAAC;QAC1B,MAAM,OAAO,GAAG,WAAW,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC;QAClD,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;YACnD,MAAM,IAAI,eAAe,CACvB,yBAAyB,KAAK,SAAS,MAAM,oBAAoB,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CACtF,CAAC;QACJ,CAAC;QACD,OAAO;IACT,CAAC;IACD,IAAI,CAAC,aAAa,CAAC,QAAQ,CAAC,KAAoB,CAAC,EAAE,CAAC;QAClD,MAAM,IAAI,eAAe,CAAC,yBAAyB,KAAK,EAAE,CAAC,CAAC;IAC9D,CAAC;AACH,CAAC"}

package/dist/dsl/types/buckets.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Bucket types for Dimensions API facet results.
+ * @module types/buckets
+ */
+/**
+ * Base bucket with id and count (always present).
+ */
+export interface BaseBucket {
+    readonly id: string | number;
+    readonly count: number;
+}
+/**
+ * Bucket with dynamic aggregation indicator properties from the API.
+ */
+export type BucketWithAggregations<TBucket extends BaseBucket = BaseBucket, TIndicators extends readonly string[] = readonly string[]> = TBucket & {
+    readonly [K in TIndicators[number]]?: number;
+};
+//# sourceMappingURL=buckets.d.ts.map

package/dist/dsl/types/buckets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"buckets.d.ts","sourceRoot":"","sources":["../../../src/dsl/types/buckets.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,MAAM,sBAAsB,CAChC,OAAO,SAAS,UAAU,GAAG,UAAU,EACvC,WAAW,SAAS,SAAS,MAAM,EAAE,GAAG,SAAS,MAAM,EAAE,IACvD,OAAO,GAAG;IACZ,QAAQ,EAAE,CAAC,IAAI,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM;CAC7C,CAAC"}

package/dist/dsl/types/buckets.js

@@ -0,0 +1,6 @@
+/**
+ * Bucket types for Dimensions API facet results.
+ * @module types/buckets
+ */
+export {};
+//# sourceMappingURL=buckets.js.map

package/dist/dsl/types/buckets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"buckets.js","sourceRoot":"","sources":["../../../src/dsl/types/buckets.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/dist/dsl/types/common.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Common type definitions shared across Dimensions API entities.
+ * @module types/common
+ */
+/**
+ * Represents an author of a publication or other research output.
+ */
+export interface Author {
+    /** Dimensions author ID */
+    id?: string;
+    /** Author's first name */
+    first_name?: string;
+    /** Author's last name */
+    last_name?: string;
+    /** Author's full name (if first/last not available) */
+    full_name?: string;
+    /** ORCID identifier */
+    orcid?: string;
+    /** Author's institutional affiliations */
+    affiliations?: Affiliation[];
+}
+/**
+ * Represents an institutional affiliation.
+ */
+export interface Affiliation {
+    /** Dimensions affiliation ID */
+    id?: string;
+    /** Institution name */
+    name: string;
+    /** City where institution is located */
+    city?: string;
+    /** State/province where institution is located */
+    state?: string;
+    /** Country where institution is located */
+    country?: string;
+}
+/**
+ * Represents a research organization (university, institute, etc.).
+ */
+export interface ResearchOrg {
+    /** Dimensions organization ID */
+    id?: string;
+    /** Organization name */
+    name: string;
+    /** City where organization is located */
+    city?: string;
+    /** Country where organization is located */
+    country?: string;
+}
+/**
+ * Represents a funding organization.
+ */
+export interface FunderOrg {
+    /** Dimensions funder ID */
+    id?: string;
+    /** Funder name */
+    name: string;
+    /** Funder acronym (e.g., "NIH", "NSF") */
+    acronym?: string;
+    /** Country where funder is based */
+    country?: string;
+}
+/**
+ * Represents a category code (FOR, SDG, etc.).
+ */
+export interface CategoryCode {
+    /** Category code identifier */
+    id: string;
+    /** Category name */
+    name: string;
+}
+/**
+ * Represents a concept with its relevance score.
+ */
+export interface ConceptScore {
+    /** Concept name */
+    concept: string;
+    /** Relevance score */
+    relevance: number;
+}
+/**
+ * Represents a journal or publication venue.
+ */
+export interface Journal {
+    /** Dimensions journal ID */
+    id?: string;
+    /** Journal title */
+    title: string;
+}
+export type { QueryExecutor } from "../../client/index.js";
+//# sourceMappingURL=common.d.ts.map

package/dist/dsl/types/common.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"common.d.ts","sourceRoot":"","sources":["../../../src/dsl/types/common.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;GAEG;AACH,MAAM,WAAW,MAAM;IACrB,2BAA2B;IAC3B,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,0BAA0B;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,yBAAyB;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,uDAAuD;IACvD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,uBAAuB;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0CAA0C;IAC1C,YAAY,CAAC,EAAE,WAAW,EAAE,CAAC;CAC9B;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,gCAAgC;IAChC,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,uBAAuB;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,wCAAwC;IACxC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kDAAkD;IAClD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,2CAA2C;IAC3C,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,iCAAiC;IACjC,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,wBAAwB;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,yCAAyC;IACzC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,4CAA4C;IAC5C,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,2BAA2B;IAC3B,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,kBAAkB;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,0CAA0C;IAC1C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,oCAAoC;IACpC,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,+BAA+B;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,oBAAoB;IACpB,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,mBAAmB;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,sBAAsB;IACtB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,OAAO;IACtB,4BAA4B;IAC5B,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,oBAAoB;IACpB,KAAK,EAAE,MAAM,CAAC;CACf;AAGD,YAAY,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/dsl/types/common.js

@@ -0,0 +1,6 @@
+/**
+ * Common type definitions shared across Dimensions API entities.
+ * @module types/common
+ */
+export {};
+//# sourceMappingURL=common.js.map

package/dist/dsl/types/common.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"common.js","sourceRoot":"","sources":["../../../src/dsl/types/common.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/dist/dsl/types/entities.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Entity type definitions for Dimensions API responses.
+ *
+ * Best-effort TypeScript shapes for API result rows. Field names and availability
+ * come from live `describe schema` (see {@link SchemaStore}); these types are not
+ * validated at runtime.
+ *
+ * @module types/entities
+ */
+/**
+ * Base row returned by structured search — always includes `id`; other fields vary by source.
+ */
+export interface DimensionsEntityBase {
+    /** Dimensions record ID */
+    id: string;
+    /** Additional fields from the API (see describe schema / return clause) */
+    [key: string]: unknown;
+}
+/** @see DimensionsEntityBase */
+export type Publication = DimensionsEntityBase;
+/** @see DimensionsEntityBase */
+export type Grant = DimensionsEntityBase;
+/** @see DimensionsEntityBase */
+export type Researcher = DimensionsEntityBase;
+/** @see DimensionsEntityBase */
+export type Patent = DimensionsEntityBase;
+/** @see DimensionsEntityBase */
+export type ClinicalTrial = DimensionsEntityBase;
+/** @see DimensionsEntityBase */
+export type Dataset = DimensionsEntityBase;
+/** @see DimensionsEntityBase */
+export type PolicyDocument = DimensionsEntityBase;
+/** @see DimensionsEntityBase */
+export type Organization = DimensionsEntityBase;
+//# sourceMappingURL=entities.d.ts.map

package/dist/dsl/types/entities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entities.d.ts","sourceRoot":"","sources":["../../../src/dsl/types/entities.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,2BAA2B;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,2EAA2E;IAC3E,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,gCAAgC;AAChC,MAAM,MAAM,WAAW,GAAG,oBAAoB,CAAC;AAE/C,gCAAgC;AAChC,MAAM,MAAM,KAAK,GAAG,oBAAoB,CAAC;AAEzC,gCAAgC;AAChC,MAAM,MAAM,UAAU,GAAG,oBAAoB,CAAC;AAE9C,gCAAgC;AAChC,MAAM,MAAM,MAAM,GAAG,oBAAoB,CAAC;AAE1C,gCAAgC;AAChC,MAAM,MAAM,aAAa,GAAG,oBAAoB,CAAC;AAEjD,gCAAgC;AAChC,MAAM,MAAM,OAAO,GAAG,oBAAoB,CAAC;AAE3C,gCAAgC;AAChC,MAAM,MAAM,cAAc,GAAG,oBAAoB,CAAC;AAElD,gCAAgC;AAChC,MAAM,MAAM,YAAY,GAAG,oBAAoB,CAAC"}

package/dist/dsl/types/entities.js

@@ -0,0 +1,11 @@
+/**
+ * Entity type definitions for Dimensions API responses.
+ *
+ * Best-effort TypeScript shapes for API result rows. Field names and availability
+ * come from live `describe schema` (see {@link SchemaStore}); these types are not
+ * validated at runtime.
+ *
+ * @module types/entities
+ */
+export {};
+//# sourceMappingURL=entities.js.map

package/dist/dsl/types/entities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entities.js","sourceRoot":"","sources":["../../../src/dsl/types/entities.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/dist/dsl/types/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Type definitions for Dimensions API.
+ * @module types
+ */
+export type { BaseBucket, BucketWithAggregations } from "./buckets.js";
+export type { Affiliation, Author, CategoryCode, ConceptScore, FunderOrg, Journal, QueryExecutor, ResearchOrg, } from "./common.js";
+export type { ClinicalTrial, Dataset, DimensionsEntityBase, Grant, Organization, Patent, PolicyDocument, Publication, Researcher, } from "./entities.js";
+export type { AggregatedFacetReturnClause, Currency, EntityReturnClause, FacetClause, FacetReturnClause, GroupedReturnClause, ReturnClause, TimeSeriesDataPoint, TimeSeriesFunction, TimeSeriesResult, TimeSeriesReturnClause, UnnestField, } from "./return-clauses.js";
+export { SUPPORTED_CURRENCIES } from "./return-clauses.js";
+export type { AffiliationInput, AffiliationResult, ClassificationEntry, ClassificationSystem, ClassifyInput, ClassifyResponse, ConceptBasic, ConceptWithScore, ExtractAffiliationsInput, ExtractAffiliationsResponse, ExtractConceptsInput, ExtractConceptsResponse, ExtractGrantsInput, ExtractGrantsResponse, } from "./special-functions.js";
+export { CLASSIFICATION_SYSTEMS } from "./special-functions.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/dsl/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/dsl/types/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,YAAY,EAAE,UAAU,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AAEvE,YAAY,EACV,WAAW,EACX,MAAM,EACN,YAAY,EACZ,YAAY,EACZ,SAAS,EACT,OAAO,EACP,aAAa,EACb,WAAW,GACZ,MAAM,aAAa,CAAC;AAErB,YAAY,EACV,aAAa,EACb,OAAO,EACP,oBAAoB,EACpB,KAAK,EACL,YAAY,EACZ,MAAM,EACN,cAAc,EACd,WAAW,EACX,UAAU,GACX,MAAM,eAAe,CAAC;AAEvB,YAAY,EACV,2BAA2B,EAC3B,QAAQ,EACR,kBAAkB,EAClB,WAAW,EACX,iBAAiB,EACjB,mBAAmB,EACnB,YAAY,EACZ,mBAAmB,EACnB,kBAAkB,EAClB,gBAAgB,EAChB,sBAAsB,EACtB,WAAW,GACZ,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAE3D,YAAY,EACV,gBAAgB,EAChB,iBAAiB,EACjB,mBAAmB,EACnB,oBAAoB,EACpB,aAAa,EACb,gBAAgB,EAChB,YAAY,EACZ,gBAAgB,EAChB,wBAAwB,EACxB,2BAA2B,EAC3B,oBAAoB,EACpB,uBAAuB,EACvB,kBAAkB,EAClB,qBAAqB,GACtB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/dsl/types/index.js

@@ -0,0 +1,7 @@
+/**
+ * Type definitions for Dimensions API.
+ * @module types
+ */
+export { SUPPORTED_CURRENCIES } from "./return-clauses.js";
+export { CLASSIFICATION_SYSTEMS } from "./special-functions.js";
+//# sourceMappingURL=index.js.map

package/dist/dsl/types/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/dsl/types/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAyCH,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAkB3D,OAAO,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/dsl/types/return-clauses.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Discriminated union types for DSL return clauses.
+ * Supports entity returns, simple facets, and aggregated facets.
+ * @module types/return-clauses
+ */
+import type { SortOrder } from "./vocabulary.js";
+/**
+ * Entity return clause.
+ * DSL: return publications[id+title]
+ */
+export interface EntityReturnClause {
+    readonly type: "entity";
+    readonly fields?: readonly string[];
+    readonly limit?: number;
+    readonly skip?: number;
+    readonly sortField?: string;
+    readonly sortOrder?: SortOrder;
+}
+/**
+ * Simple facet return clause (no aggregations).
+ * DSL: return year limit 100
+ */
+export interface FacetReturnClause<F extends string = string> {
+    readonly type: "facet";
+    readonly field: F;
+    readonly limit?: number;
+}
+/**
+ * Aggregated facet return clause with indicators and sorting.
+ * DSL: return funders aggregate rcr_avg, altmetric_median sort by rcr_avg desc limit 10
+ */
+export interface AggregatedFacetReturnClause<F extends string = string, I extends string = string> {
+    readonly type: "aggregated_facet";
+    readonly field: F;
+    readonly indicators: readonly I[];
+    readonly sortBy?: I | "count";
+    readonly sortOrder?: SortOrder;
+    readonly limit?: number;
+}
+/**
+ * Union of all return clause types.
+ * @template F - The facet field type
+ * @template I - The indicator type
+ */
+export type ReturnClause<F extends string = string, I extends string = string> = EntityReturnClause | FacetReturnClause<F> | AggregatedFacetReturnClause<F, I>;
+/**
+ * Type for facet clauses only (excludes entity return).
+ * @template F - The facet field type
+ * @template I - The indicator type
+ */
+export type FacetClause<F extends string = string, I extends string = string> = FacetReturnClause<F> | AggregatedFacetReturnClause<F, I>;
+/**
+ * Supported currencies for funding_per_year function.
+ */
+export declare const SUPPORTED_CURRENCIES: readonly ["AUD", "CAD", "CHF", "CNY", "EUR", "GBP", "JPY", "NZD", "USD"];
+/**
+ * Currency type for funding operations.
+ */
+export type Currency = (typeof SUPPORTED_CURRENCIES)[number];
+/**
+ * Time-series return clause types.
+ */
+export type TimeSeriesFunction = "citations_per_year" | "funding_per_year";
+/**
+ * Time-series return clause for citations_per_year or funding_per_year.
+ * DSL: return citations_per_year(2010, 2023)
+ * DSL: return funding_per_year(2015, 2023, "USD")
+ */
+export interface TimeSeriesReturnClause {
+    readonly type: "time_series";
+    readonly function: TimeSeriesFunction;
+    readonly startYear: number;
+    readonly endYear: number;
+    /** Currency for funding_per_year (required for funding, ignored for citations) */
+    readonly currency?: Currency;
+}
+/**
+ * A single time-series data point.
+ */
+export interface TimeSeriesDataPoint {
+    readonly year: number;
+    readonly value: number;
+}
+/**
+ * Result structure for time-series functions.
+ */
+export interface TimeSeriesResult {
+    readonly data: readonly TimeSeriesDataPoint[];
+}
+/**
+ * Unnest field specification for flattening nested data.
+ * DSL: unnest(researchers)
+ */
+export interface UnnestField {
+    readonly type: "unnest";
+    readonly field: string;
+}
+/**
+ * Grouped return clause for organizing results into named groups.
+ * DSL: return in "docs" publications[id + title]
+ */
+export interface GroupedReturnClause {
+    readonly type: "grouped";
+    readonly groupName: string;
+    readonly entityOrFacet: EntityReturnClause | FacetReturnClause | AggregatedFacetReturnClause;
+}
+//# sourceMappingURL=return-clauses.d.ts.map

package/dist/dsl/types/return-clauses.d.ts.map

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

package/dist/dsl/types/return-clauses.js

@@ -0,0 +1,22 @@
+/**
+ * Discriminated union types for DSL return clauses.
+ * Supports entity returns, simple facets, and aggregated facets.
+ * @module types/return-clauses
+ */
+// #region Time-Series Return Types
+/**
+ * Supported currencies for funding_per_year function.
+ */
+export const SUPPORTED_CURRENCIES = [
+    "AUD",
+    "CAD",
+    "CHF",
+    "CNY",
+    "EUR",
+    "GBP",
+    "JPY",
+    "NZD",
+    "USD",
+];
+// #endregion
+//# sourceMappingURL=return-clauses.js.map

package/dist/dsl/types/return-clauses.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"return-clauses.js","sourceRoot":"","sources":["../../../src/dsl/types/return-clauses.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AA2DH,mCAAmC;AAEnC;;GAEG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,KAAK;IACL,KAAK;IACL,KAAK;IACL,KAAK;IACL,KAAK;IACL,KAAK;IACL,KAAK;IACL,KAAK;IACL,KAAK;CACG,CAAC;AAoEX,aAAa"}