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

package/src/dsl/types/index.ts

@@ -0,0 +1,63 @@
+/**
+ * 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";

package/src/dsl/types/return-clauses.ts

@@ -0,0 +1,147 @@
+/**
+ * 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>;
+
+// #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",
+] as const;
+
+/**
+ * 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[];
+}
+
+// #endregion
+
+// #region Unnest Types
+
+/**
+ * Unnest field specification for flattening nested data.
+ * DSL: unnest(researchers)
+ */
+export interface UnnestField {
+  readonly type: "unnest";
+  readonly field: string;
+}
+
+// #endregion
+
+// #region Grouped Return Types
+
+/**
+ * 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;
+}
+
+// #endregion

package/src/dsl/types/special-functions.ts

@@ -0,0 +1,220 @@
+/**
+ * Type definitions for Dimensions DSL special functions.
+ * Includes types for classify(), extract_concepts(), and similar_documents().
+ * @module types/special-functions
+ */
+
+/**
+ * Array of valid classification systems for runtime validation.
+ * Use this constant in Zod schemas and other runtime checks.
+ */
+export const CLASSIFICATION_SYSTEMS = [
+  "FOR",
+  "FOR_2020",
+  "SDG",
+  "SDG_2021",
+  "RCDC",
+  "HRCS_HC",
+  "HRCS_RAC",
+  "HRA",
+  "BRA",
+  "ICRP_CSO",
+  "ICRP_CT",
+  "UOA",
+] as const;
+
+/**
+ * Classification systems supported by the Dimensions API.
+ * These systems categorize research into standardized taxonomies.
+ */
+export type ClassificationSystem =
+  | "FOR"
+  | "FOR_2020"
+  | "SDG"
+  | "SDG_2021"
+  | "RCDC"
+  | "HRCS_HC"
+  | "HRCS_RAC"
+  | "HRA"
+  | "BRA"
+  | "ICRP_CSO"
+  | "ICRP_CT"
+  | "UOA";
+
+/**
+ * A single classification entry returned by the classify() function.
+ * Contains an identifier and human-readable name for a category.
+ */
+export interface ClassificationEntry {
+  /** The classification code identifier */
+  readonly id: string;
+  /** The human-readable name of the classification */
+  readonly name: string;
+}
+
+/**
+ * Response from the classify() function.
+ * Keys are the classification system name, values are arrays of classification entries.
+ *
+ * @template S - The classification system type
+ *
+ * @example
+ * ```typescript
+ * // FOR classification response
+ * const response: ClassifyResponse<"FOR"> = {
+ *   FOR: [
+ *     { id: "1117", name: "Public Health and Health Services" },
+ *     { id: "1103", name: "Clinical Sciences" }
+ *   ]
+ * };
+ * ```
+ */
+export type ClassifyResponse<S extends ClassificationSystem = ClassificationSystem> = {
+  readonly [K in S]: readonly ClassificationEntry[];
+};
+
+/**
+ * A concept extracted without a relevance score.
+ * Used when return_scores is false or not specified.
+ */
+export interface ConceptBasic {
+  /** The extracted concept string */
+  readonly concept: string;
+}
+
+/**
+ * A concept extracted with its relevance score.
+ * Used when return_scores=true is specified.
+ */
+export interface ConceptWithScore {
+  /** The extracted concept string */
+  readonly concept: string;
+  /** Relevance score indicating how strongly the concept relates to the text */
+  readonly relevance: number;
+}
+
+/**
+ * Response from the extract_concepts() function.
+ * Structure depends on whether return_scores was requested.
+ *
+ * @template WithScores - Whether relevance scores are included
+ *
+ * @example
+ * ```typescript
+ * // Without scores (default)
+ * const simple: ExtractConceptsResponse<false> = {
+ *   extracted_concepts: ["machine learning", "neural networks", "deep learning"]
+ * };
+ *
+ * // With scores
+ * const withScores: ExtractConceptsResponse<true> = {
+ *   extracted_concepts: [
+ *     { concept: "machine learning", relevance: 0.95 },
+ *     { concept: "neural networks", relevance: 0.87 }
+ *   ]
+ * };
+ * ```
+ */
+export type ExtractConceptsResponse<WithScores extends boolean = false> = WithScores extends true
+  ? { readonly extracted_concepts: readonly ConceptWithScore[] }
+  : { readonly extracted_concepts: readonly string[] };
+
+/**
+ * Input parameters for the classify() function.
+ */
+export interface ClassifyInput {
+  /** Document title (at least title or abstract must be provided) */
+  readonly title?: string;
+  /** Document abstract (at least title or abstract must be provided) */
+  readonly abstract?: string;
+  /** Classification system to use */
+  readonly system: ClassificationSystem;
+}
+
+/**
+ * Input parameters for the extract_concepts() function.
+ */
+export interface ExtractConceptsInput {
+  /** Text to extract concepts from */
+  readonly text: string;
+  /** Whether to include relevance scores in the response */
+  readonly returnScores?: boolean;
+}
+
+// #region extract_affiliations() Types
+
+/**
+ * A single affiliation input for extract_affiliations().
+ * Can be either freetext (affiliation field) or structured (name, city, state, country).
+ */
+export interface AffiliationInput {
+  /** Freetext affiliation string (use this OR structured fields) */
+  readonly affiliation?: string;
+  /** Organization name (structured input) */
+  readonly name?: string;
+  /** City (structured input) */
+  readonly city?: string;
+  /** State/province (structured input) */
+  readonly state?: string;
+  /** Country (structured input) */
+  readonly country?: string;
+}
+
+/**
+ * Input parameters for the extract_affiliations() function.
+ */
+export interface ExtractAffiliationsInput {
+  /** Array of affiliation inputs to resolve */
+  readonly affiliations: readonly AffiliationInput[];
+  /** Results detail level: "basic" (default), "full", or "publisher" */
+  readonly results?: "basic" | "full" | "publisher";
+}
+
+/**
+ * A single affiliation result from extract_affiliations().
+ */
+export interface AffiliationResult {
+  /** The organization identifier (e.g., "grid.xxx" or "or.xxx") */
+  readonly id: string;
+  /** The canonical organization name */
+  readonly name: string;
+  /** Country of the organization */
+  readonly country?: string;
+  /** Match confidence score (0-1) */
+  readonly score?: number;
+}
+
+/**
+ * Response from the extract_affiliations() function.
+ */
+export interface ExtractAffiliationsResponse {
+  readonly extracted_affiliations: readonly AffiliationResult[];
+}
+
+// #endregion
+
+// #region extract_grants() Types
+
+/**
+ * Input parameters for the extract_grants() function.
+ */
+export interface ExtractGrantsInput {
+  /** Grant number to look up */
+  readonly grantNumber: string;
+  /** FundRef ID of the funder (alternative to funderName) */
+  readonly fundref?: string;
+  /** Funder name (alternative to fundref) */
+  readonly funderName?: string;
+}
+
+/**
+ * Response from the extract_grants() function.
+ * The Dimensions API resolves a grant number to a single grant ID.
+ * Returns `null` when no matching grant is found.
+ */
+export interface ExtractGrantsResponse {
+  /** Resolved Dimensions grant ID (e.g. "grant.2544064"), or null if not found */
+  readonly grant_id: string | null;
+}
+
+// #endregion

package/src/dsl/types/vocabulary.ts

@@ -0,0 +1,82 @@
+/**
+ * Dimensions DSL vocabulary types and runtime validation lists.
+ * @module types/vocabulary
+ */
+
+/** Comparison operators supported in WHERE clause filters. */
+export type Operator = "=" | "!=" | "<" | ">" | "<=" | ">=" | "in" | "~" | "@";
+
+/** Backward-compatible alias for {@link Operator}. */
+export type WhereOperator = Operator;
+
+/** Supported entity types (data sources) in the Dimensions DSL. */
+export type EntityType =
+  | "publications"
+  | "grants"
+  | "researchers"
+  | "patents"
+  | "clinical_trials"
+  | "datasets"
+  | "policy_documents"
+  | "organizations";
+
+/** Search indexes for `search <source> in <index> for "..."` clauses. */
+export type SearchIndex =
+  | "full_data"
+  | "full_data_exact"
+  | "title_abstract_only"
+  | "title_only"
+  | "authors"
+  | "inventors"
+  | "investigators"
+  | "concepts"
+  | "funding"
+  | "acknowledgements"
+  | "raw_affiliations"
+  | "assignees"
+  | "title_abstract_claims";
+
+/** Sort direction for order-by clauses. */
+export type SortOrder = "asc" | "desc";
+
+/** Valid operators for runtime validation. */
+export const VALID_OPERATORS: readonly Operator[] = [
+  "=",
+  "!=",
+  ">",
+  "<",
+  ">=",
+  "<=",
+  "in",
+  "~",
+  "@",
+] as const;
+
+/** Valid entity types for runtime validation. */
+export const VALID_ENTITIES: readonly EntityType[] = [
+  "publications",
+  "grants",
+  "researchers",
+  "patents",
+  "clinical_trials",
+  "datasets",
+  "policy_documents",
+  "organizations",
+] as const;
+
+/** Valid search indexes for runtime validation. */
+export const VALID_INDEXES: readonly SearchIndex[] = [
+  "full_data",
+  "full_data_exact",
+  "title_abstract_only",
+  "title_only",
+  "authors",
+  "inventors",
+  "investigators",
+  "concepts",
+  "funding",
+  "acknowledgements",
+  "raw_affiliations",
+  "assignees",
+  "title_abstract_claims",
+] as const;