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

package/CHANGELOG.md

@@ -0,0 +1,61 @@
+# Changelog
+
+## 0.5.3
+
+Republish on public npm after package unpublish (0.5.2 cannot be re-used).
+
+## 0.5.2
+
+### Packaging
+
+- Resolve `catalog:` dependencies in published npm manifest (use `pnpm pack` + `npm publish` tarball)
+
+## 0.5.1
+
+### Packaging
+
+- Fix npm publish stripping CLI `bin` entries (wrappers under `bin/` per npm 11)
+
+## 0.5.0
+
+### Tool surface
+
+- Remove dedicated MCP tools: KWQ (`build_query`, `ensemble_queries`), NLP (`classify_text`, `extract_concepts`), similarity search, profile lookup, `recent_high_impact`
+- Keep `extract_affiliations`, `extract_grants`; classify/extract/similar remain available via **`execute_dsl`**
+
+### Packaging & install
+
+- Rename npm package to `@digital-science-dsl/dimensions-analytics-mcp` (was `@digital-science/dsl-mcp`)
+- Rename CLIs to `dimensions-analytics-mcp` and `dimensions-analytics-mcp-http`
+- Publish to public npm; guided installer no longer requires a GitHub token
+- Add `docs/IDENTIFIERS.md` mapping product name to technical names
+
+### Hosted deployment
+
+- Add Streamable HTTP entrypoint (`dimensions-analytics-mcp-http`) at `POST /mcp` with `GET /health`
+- Add dsl-service adapter (`POST /query`, JSON body, service basic-auth, `X-DIMENSIONS-USER`)
+- Add Bearer API key validation via Radar `POST /api/auth.json`
+- Omit `fetch_search_pages` on hosted (local disk export)
+- Schema warmup uses derived identity `mcp@<DSL_HOST>` (no bootstrap env var)
+- Docker image (`apps/mcp/Dockerfile`) and Kubernetes example (`deploy/kubernetes/dsl-mcp.yaml`) — **moved to `dimensions-analytics-mcp-deploy` repo**
+
+### Testing & CI
+
+- Mock hosted e2e tests (default CI, no secrets)
+- Nightly/manual integration workflow for live stdio and hosted smoke
+- Docker build/push workflow — **`dimensions-analytics-mcp-deploy` repo**
+
+## 0.4.0
+
+- Pagination on `search_*` (`skip`, `page`, metadata)
+- `fetch_search_pages` tool: page, aggregate, and file export modes (JSONL + CSV)
+- Reasonable-use policy guardrails (`dimensions://schema/policy`, `confirmLargeFetch`)
+- Per-source example resources: `dimensions://examples/{source}`
+
+## 0.3.0
+
+- Consolidate monorepo into single `@digital-science/dsl-mcp` package (`apps/mcp` only)
+
+## 0.1.0
+
+Initial release from [digital-science/dimensions-analytics-mcp](https://github.com/digital-science/dimensions-analytics-mcp) as npm package `@digital-science/dsl-mcp`.

package/README.md

@@ -0,0 +1,152 @@
+# Dimensions Analytics MCP
+
+Model Context Protocol (MCP) server for the Dimensions Analytics API — enables AI assistants to search and analyze linked research data with the Dimensions DSL.
+
+**Transport:** stdio (`dimensions-analytics-mcp`) for local use. A hosted remote option (URL + Bearer token) is **coming soon** — see [Installation — Hosted Dimensions Analytics MCP](https://github.com/digital-science/dimensions-analytics-mcp/blob/main/docs/INSTALLATION.md#hosted-dimensions-analytics-mcp-coming-soon).
+
+## What It Does
+
+Dimensions Analytics MCP provides access to Dimensions, the world's largest linked research information database with over 140M publications, grants, patents, clinical trials, and more. It enables Claude and other MCP-compatible AI assistants to search and analyze research data.
+
+## Available Tools
+
+### Search Tools
+
+| Tool | Description |
+| ---- | ----------- |
+| `search_publications` | Search research articles, preprints, and books with citation metrics |
+| `search_grants` | Search research grants and funding awards |
+| `search_researchers` | Search researcher profiles with publication counts and affiliations |
+| `search_patents` | Search patents with assignee and filing information |
+| `search_clinical_trials` | Search clinical trials by phase, condition, or status |
+| `search_datasets` | Search research datasets and repositories |
+| `search_policy_documents` | Search policy briefs and government documents |
+| `search_organizations` | Search universities, research institutes, and companies |
+| `fetch_search_pages` | Paginated / batch search (page, aggregate, JSONL/CSV file export) — **local stdio only** |
+
+### Lookup Tools
+
+| Tool | Description |
+| ---- | ----------- |
+| `get_by_doi` | Retrieve publication by DOI |
+| `get_by_pmid` | Retrieve publication by PubMed ID |
+| `get_by_id` | Retrieve any entity by Dimensions ID |
+
+### Analytics & Trend Tools
+
+| Tool | Description |
+| ---- | ----------- |
+| `aggregate_query` | Numeric aggregation (sum/avg/count) over any entity with grouping |
+| `facet_query` | Facet counts for top values of any field |
+| `citation_trend` | Citation counts over time for a topic or entity |
+| `funding_trend` | Funding awarded over time for a topic or entity |
+
+### Entity Resolution Tools
+
+| Tool | Description |
+| ---- | ----------- |
+| `extract_affiliations` | Resolve organization affiliations to GRID/ROR identifiers |
+| `extract_grants` | Resolve grant numbers to full grant records |
+| `execute_dsl` | Execute raw Dimensions DSL queries (includes classify, extract concepts, similarity, etc.) |
+
+### Schema Tools
+
+| Tool | Description |
+| ---- | ----------- |
+| `describe_schema` | Summarize live describe schema (sources, entities, limits) |
+| `refresh_schema` | Reload describe schema from the API |
+
+### Removed in 0.5.0
+
+Dedicated MCP tools for KWQ (`build_query`, `ensemble_queries`), NLP (`classify_text`, `extract_concepts`), similarity search, profile lookup, and `recent_high_impact` were removed. Use **`execute_dsl`** for those DSL capabilities.
+
+## Quick Start
+
+**Easiest** — one-line install (no clone required):
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/digital-science/dimensions-analytics-mcp/main/scripts/install.sh | bash
+```
+
+```powershell
+irm https://raw.githubusercontent.com/digital-science/dimensions-analytics-mcp/main/scripts/install.ps1 | iex
+```
+
+See [Installation](https://github.com/digital-science/dimensions-analytics-mcp/blob/main/docs/INSTALLATION.md) for manual setup.
+
+### Build from source (developers)
+
+```bash
+pnpm install
+pnpm run build
+export DIMENSIONS_API_KEY=your-key
+node apps/mcp/dist/main.js          # stdio
+```
+
+### Claude Desktop (stdio)
+
+```json
+{
+  "mcpServers": {
+    "dimensions": {
+      "command": "node",
+      "args": ["/path/to/dimensions-analytics-mcp/apps/mcp/dist/main.js"],
+      "env": {
+        "DIMENSIONS_API_KEY": "your-api-key"
+      }
+    }
+  }
+}
+```
+
+### Hosted remote MCP (coming soon)
+
+A hosted Dimensions Analytics MCP endpoint (URL + Bearer token, no local install) is **not available yet**. We will announce it in the near future. See [Installation — Hosted Dimensions Analytics MCP](https://github.com/digital-science/dimensions-analytics-mcp/blob/main/docs/INSTALLATION.md#hosted-dimensions-analytics-mcp-coming-soon).
+
+## Examples and usage
+
+**[Usage guide](https://github.com/digital-science/dimensions-analytics-mcp/blob/main/docs/USAGE.md)** — workflows, JSON tool examples, DSL snippets, and natural-language prompts.
+
+Quick prompt examples:
+
+```text
+Find the top 10 most-cited publications about CRISPR from the last 5 years
+```
+
+```text
+Facet journals for "quantum computing" publications since 2020
+```
+
+## Documentation
+
+**This package**
+
+- [Usage guide](https://github.com/digital-science/dimensions-analytics-mcp/blob/main/docs/USAGE.md) — **start here** for examples
+- [Deployment](https://github.com/digital-science/dimensions-analytics-mcp/blob/main/docs/DEPLOYMENT.md) — local stdio setup; hosted option (coming soon)
+- [Configuration](https://github.com/digital-science/dimensions-analytics-mcp/blob/main/docs/CONFIGURATION.md) — env vars
+- [MCP field aliases](https://github.com/digital-science/dimensions-analytics-mcp/blob/main/docs/MCP_FIELD_ALIASES.md) — alias reference for tool users
+
+**Repository** ([dimensions-analytics-mcp](https://github.com/digital-science/dimensions-analytics-mcp))
+
+- [Root README](https://github.com/digital-science/dimensions-analytics-mcp/blob/main/README.md)
+- [Installation](https://github.com/digital-science/dimensions-analytics-mcp/blob/main/docs/INSTALLATION.md)
+
+**External**
+
+- [Dimensions API Docs](https://docs.dimensions.ai/)
+- [Model Context Protocol spec](https://modelcontextprotocol.io/)
+
+## Development
+
+```bash
+pnpm install   # from repo root
+pnpm run build
+
+pnpm run test              # unit + mock hosted e2e
+pnpm run integration:smoke # live stdio smoke (DIMENSIONS_API_KEY)
+pnpm run typecheck
+```
+
+## License
+
+MIT

package/bin/dimensions-analytics-mcp-http.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "../dist/http-main.js";

package/bin/dimensions-analytics-mcp.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "../dist/main.js";

package/dist/client/auth/config-loaders.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Configuration loaders for JWT AuthConfig.
+ * @module client/auth/config-loaders
+ */
+import type { AuthConfig, JwtAuthConfig } from "./types.js";
+/** Options for loading config from environment variables. */
+export interface FromEnvOptions {
+    /** Env prefix (default `DIMENSIONS` → `DIMENSIONS_API_KEY`) */
+    prefix?: string;
+}
+/**
+ * Load JWT auth config from environment variables.
+ * @param type - Must be `"jwt"`
+ * @param options - Optional env prefix
+ * @returns Validated JwtAuthConfig
+ */
+export declare function fromEnv(type: "jwt", options?: FromEnvOptions): JwtAuthConfig;
+/** Load JWT auth config from a JSON file. */
+export declare function fromPath(filePath: string): AuthConfig;
+/** Validate and return JWT auth config from an object. */
+export declare function fromObject(obj: unknown): AuthConfig;
+//# sourceMappingURL=config-loaders.d.ts.map

package/dist/client/auth/config-loaders.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-loaders.d.ts","sourceRoot":"","sources":["../../../src/client/auth/config-loaders.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,OAAO,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE5D,6DAA6D;AAC7D,MAAM,WAAW,cAAc;IAC7B,+DAA+D;IAC/D,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,KAAK,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,aAAa,CAwB5E;AAED,6CAA6C;AAC7C,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,UAAU,CAoBrD;AAED,0DAA0D;AAC1D,wBAAgB,UAAU,CAAC,GAAG,EAAE,OAAO,GAAG,UAAU,CAQnD"}

package/dist/client/auth/config-loaders.js

@@ -0,0 +1,68 @@
+/**
+ * Configuration loaders for JWT AuthConfig.
+ * @module client/auth/config-loaders
+ */
+import { readFileSync } from "node:fs";
+import { ValidationError } from "../errors.js";
+import { JwtAuthConfigSchema } from "./schemas.js";
+/**
+ * Load JWT auth config from environment variables.
+ * @param type - Must be `"jwt"`
+ * @param options - Optional env prefix
+ * @returns Validated JwtAuthConfig
+ */
+export function fromEnv(type, options) {
+    if (type !== "jwt") {
+        throw new ValidationError("Only JWT auth is supported");
+    }
+    const envPrefix = options?.prefix ?? "DIMENSIONS";
+    const apiKey = process.env[`${envPrefix}_API_KEY`];
+    if (!apiKey) {
+        throw new ValidationError(`Missing required environment variable: ${envPrefix}_API_KEY`);
+    }
+    const authUrl = process.env[`${envPrefix}_AUTH_URL`];
+    const tokenCacheDuration = process.env[`${envPrefix}_TOKEN_CACHE_DURATION`];
+    const timeout = process.env[`${envPrefix}_TIMEOUT`];
+    return {
+        type: "jwt",
+        apiKey,
+        ...(authUrl && { authUrl }),
+        ...(tokenCacheDuration && {
+            tokenCacheDuration: Number.parseInt(tokenCacheDuration, 10),
+        }),
+        ...(timeout && { timeout: Number.parseInt(timeout, 10) }),
+    };
+}
+/** Load JWT auth config from a JSON file. */
+export function fromPath(filePath) {
+    let fileContent;
+    try {
+        fileContent = readFileSync(filePath, "utf-8");
+    }
+    catch (error) {
+        throw new ValidationError(`Failed to read config file: ${filePath}`, {
+            cause: error instanceof Error ? error.message : String(error),
+        });
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(fileContent);
+    }
+    catch (error) {
+        throw new ValidationError(`Invalid JSON in config file: ${filePath}`, {
+            cause: error instanceof Error ? error.message : String(error),
+        });
+    }
+    return fromObject(parsed);
+}
+/** Validate and return JWT auth config from an object. */
+export function fromObject(obj) {
+    const parseResult = JwtAuthConfigSchema.safeParse(obj);
+    if (!parseResult.success) {
+        throw new ValidationError(`Invalid auth configuration: ${parseResult.error.message}`, {
+            issues: parseResult.error.issues,
+        });
+    }
+    return parseResult.data;
+}
+//# sourceMappingURL=config-loaders.js.map

package/dist/client/auth/config-loaders.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-loaders.js","sourceRoot":"","sources":["../../../src/client/auth/config-loaders.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AASnD;;;;;GAKG;AACH,MAAM,UAAU,OAAO,CAAC,IAAW,EAAE,OAAwB;IAC3D,IAAI,IAAI,KAAK,KAAK,EAAE,CAAC;QACnB,MAAM,IAAI,eAAe,CAAC,4BAA4B,CAAC,CAAC;IAC1D,CAAC;IAED,MAAM,SAAS,GAAG,OAAO,EAAE,MAAM,IAAI,YAAY,CAAC;IAClD,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,SAAS,UAAU,CAAC,CAAC;IACnD,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,eAAe,CAAC,0CAA0C,SAAS,UAAU,CAAC,CAAC;IAC3F,CAAC;IAED,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,SAAS,WAAW,CAAC,CAAC;IACrD,MAAM,kBAAkB,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,SAAS,uBAAuB,CAAC,CAAC;IAC5E,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,SAAS,UAAU,CAAC,CAAC;IAEpD,OAAO;QACL,IAAI,EAAE,KAAK;QACX,MAAM;QACN,GAAG,CAAC,OAAO,IAAI,EAAE,OAAO,EAAE,CAAC;QAC3B,GAAG,CAAC,kBAAkB,IAAI;YACxB,kBAAkB,EAAE,MAAM,CAAC,QAAQ,CAAC,kBAAkB,EAAE,EAAE,CAAC;SAC5D,CAAC;QACF,GAAG,CAAC,OAAO,IAAI,EAAE,OAAO,EAAE,MAAM,CAAC,QAAQ,CAAC,OAAO,EAAE,EAAE,CAAC,EAAE,CAAC;KAC1D,CAAC;AACJ,CAAC;AAED,6CAA6C;AAC7C,MAAM,UAAU,QAAQ,CAAC,QAAgB;IACvC,IAAI,WAAmB,CAAC;IACxB,IAAI,CAAC;QACH,WAAW,GAAG,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IAChD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,eAAe,CAAC,+BAA+B,QAAQ,EAAE,EAAE;YACnE,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;SAC9D,CAAC,CAAC;IACL,CAAC;IAED,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC;IACnC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,eAAe,CAAC,gCAAgC,QAAQ,EAAE,EAAE;YACpE,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;SAC9D,CAAC,CAAC;IACL,CAAC;IAED,OAAO,UAAU,CAAC,MAAM,CAAC,CAAC;AAC5B,CAAC;AAED,0DAA0D;AAC1D,MAAM,UAAU,UAAU,CAAC,GAAY;IACrC,MAAM,WAAW,GAAG,mBAAmB,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;IACvD,IAAI,CAAC,WAAW,CAAC,OAAO,EAAE,CAAC;QACzB,MAAM,IAAI,eAAe,CAAC,+BAA+B,WAAW,CAAC,KAAK,CAAC,OAAO,EAAE,EAAE;YACpF,MAAM,EAAE,WAAW,CAAC,KAAK,CAAC,MAAM;SACjC,CAAC,CAAC;IACL,CAAC;IACD,OAAO,WAAW,CAAC,IAAI,CAAC;AAC1B,CAAC"}

package/dist/client/auth/decorators/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Auth provider decorators.
+ * @module core/auth/decorators
+ */
+export type { CachingOptions } from "./with-caching.js";
+export { withCaching } from "./with-caching.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/client/auth/decorators/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/client/auth/decorators/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,YAAY,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/client/auth/decorators/index.js

@@ -0,0 +1,6 @@
+/**
+ * Auth provider decorators.
+ * @module core/auth/decorators
+ */
+export { withCaching } from "./with-caching.js";
+//# sourceMappingURL=index.js.map

package/dist/client/auth/decorators/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/client/auth/decorators/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/client/auth/decorators/with-caching.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Caching decorator for AuthProvider.
+ * @module core/auth/decorators/with-caching
+ */
+import type { AuthProvider } from "../types.js";
+/**
+ * Configuration options for the caching decorator.
+ */
+export interface CachingOptions {
+    /**
+     * Cache duration in milliseconds.
+     * Headers will be refreshed after this time.
+     * @default 3600000 (1 hour)
+     */
+    cacheDurationMs?: number;
+    /**
+     * Buffer before expiry to trigger refresh, as a decimal (0-1).
+     * E.g., 0.1 means refresh when 90% of TTL has passed.
+     * @default 0.1
+     */
+    expiryBuffer?: number;
+    /**
+     * Initial backoff delay in milliseconds after a failed fetch.
+     * Grows exponentially on consecutive failures up to {@link failureBackoffMaxMs}.
+     * @default 1000
+     */
+    failureBackoffMs?: number;
+    /**
+     * Maximum backoff delay in milliseconds. Caps exponential growth.
+     * @default 60000
+     */
+    failureBackoffMaxMs?: number;
+    /**
+     * Multiplication factor applied to the base delay on each consecutive failure.
+     * Set to 1 for flat (non-exponential) backoff.
+     * @default 2
+     */
+    failureBackoffFactor?: number;
+    /**
+     * Jitter as a fraction of the computed delay (0–1), e.g. 0.1 = ±10%.
+     * Prevents thundering herd by spreading retry times across clients.
+     * Set to 0 for deterministic delays (useful in tests).
+     * @default 0.1
+     */
+    failureBackoffJitter?: number;
+}
+/**
+ * Wraps an AuthProvider with caching behavior.
+ *
+ * Features:
+ * - Caches getHeaders() results with configurable TTL
+ * - Deduplicates concurrent calls (reuses in-flight promise)
+ * - Calls underlying provider's getHeaders() when cache expires
+ * - Propagates errors (no stale fallback)
+ * - Implements exponential backoff with jitter after failures to prevent thundering herd
+ *
+ * @param provider - The AuthProvider to wrap
+ * @param options - Caching configuration
+ * @returns A new AuthProvider with caching behavior
+ *
+ * @example
+ * ```typescript
+ * const baseProvider = new JwtAuthProvider(config);
+ * const cachedProvider = withCaching(baseProvider, {
+ *   cacheDurationMs: 3600000,    // 1 hour
+ *   expiryBuffer: 0.1,           // Refresh at 90% of TTL
+ *   failureBackoffMs: 1000,      // Initial backoff: 1s
+ *   failureBackoffMaxMs: 60000,  // Cap at 60s
+ *   failureBackoffFactor: 2,     // Double each failure: 1s, 2s, 4s, 8s...
+ *   failureBackoffJitter: 0.1,   // ±10% jitter
+ * });
+ *
+ * // First call fetches headers
+ * const headers1 = await cachedProvider.getHeaders();
+ *
+ * // Subsequent calls return cached value
+ * const headers2 = await cachedProvider.getHeaders();
+ * ```
+ */
+export declare function withCaching(provider: AuthProvider, options?: CachingOptions): AuthProvider;
+//# sourceMappingURL=with-caching.d.ts.map

package/dist/client/auth/decorators/with-caching.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"with-caching.d.ts","sourceRoot":"","sources":["../../../../src/client/auth/decorators/with-caching.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAc,YAAY,EAAE,MAAM,aAAa,CAAC;AAE5D;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B;;;OAGG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAE7B;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAE9B;;;;;OAKG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B;AAoBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,YAAY,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,YAAY,CAmI1F"}

package/dist/client/auth/decorators/with-caching.js

@@ -0,0 +1,168 @@
+/**
+ * Caching decorator for AuthProvider.
+ * @module core/auth/decorators/with-caching
+ */
+/** Default cache duration: 1 hour */
+const DEFAULT_CACHE_DURATION_MS = 3600000;
+/** Default expiry buffer: 10% */
+const DEFAULT_EXPIRY_BUFFER = 0.1;
+/** Default failure backoff: 1 second */
+const DEFAULT_FAILURE_BACKOFF_MS = 1000;
+/** Default max backoff delay: 60 seconds */
+const DEFAULT_FAILURE_BACKOFF_MAX_MS = 60_000;
+/** Default backoff multiplication factor */
+const DEFAULT_FAILURE_BACKOFF_FACTOR = 2;
+/** Default jitter fraction: ±10% */
+const DEFAULT_FAILURE_BACKOFF_JITTER = 0.1;
+/**
+ * Wraps an AuthProvider with caching behavior.
+ *
+ * Features:
+ * - Caches getHeaders() results with configurable TTL
+ * - Deduplicates concurrent calls (reuses in-flight promise)
+ * - Calls underlying provider's getHeaders() when cache expires
+ * - Propagates errors (no stale fallback)
+ * - Implements exponential backoff with jitter after failures to prevent thundering herd
+ *
+ * @param provider - The AuthProvider to wrap
+ * @param options - Caching configuration
+ * @returns A new AuthProvider with caching behavior
+ *
+ * @example
+ * ```typescript
+ * const baseProvider = new JwtAuthProvider(config);
+ * const cachedProvider = withCaching(baseProvider, {
+ *   cacheDurationMs: 3600000,    // 1 hour
+ *   expiryBuffer: 0.1,           // Refresh at 90% of TTL
+ *   failureBackoffMs: 1000,      // Initial backoff: 1s
+ *   failureBackoffMaxMs: 60000,  // Cap at 60s
+ *   failureBackoffFactor: 2,     // Double each failure: 1s, 2s, 4s, 8s...
+ *   failureBackoffJitter: 0.1,   // ±10% jitter
+ * });
+ *
+ * // First call fetches headers
+ * const headers1 = await cachedProvider.getHeaders();
+ *
+ * // Subsequent calls return cached value
+ * const headers2 = await cachedProvider.getHeaders();
+ * ```
+ */
+export function withCaching(provider, options) {
+    const cacheDurationMs = options?.cacheDurationMs ?? DEFAULT_CACHE_DURATION_MS;
+    const expiryBuffer = options?.expiryBuffer ?? DEFAULT_EXPIRY_BUFFER;
+    const failureBackoffMs = options?.failureBackoffMs ?? DEFAULT_FAILURE_BACKOFF_MS;
+    const failureBackoffMaxMs = options?.failureBackoffMaxMs ?? DEFAULT_FAILURE_BACKOFF_MAX_MS;
+    const failureBackoffFactor = options?.failureBackoffFactor ?? DEFAULT_FAILURE_BACKOFF_FACTOR;
+    const failureBackoffJitter = options?.failureBackoffJitter ?? DEFAULT_FAILURE_BACKOFF_JITTER;
+    let cachedHeaders = null;
+    let cacheExpiry = 0;
+    let refreshPromise = null;
+    let failureCount = 0;
+    let backoffDeadline = 0;
+    /**
+     * Calculate the effective expiry time with buffer.
+     * @param durationMs - Full cache duration
+     * @returns Expiry timestamp with buffer applied
+     */
+    const calculateExpiry = (durationMs) => {
+        // Buffer is at least 1 minute, but never more than 90% of duration
+        const bufferMs = Math.min(Math.max(durationMs * expiryBuffer, 60000), durationMs * 0.9);
+        return Date.now() + durationMs - bufferMs;
+    };
+    /**
+     * Calculates the backoff delay for a given consecutive failure count.
+     * Uses exponential backoff with multiplicative jitter.
+     * @param count - Number of consecutive failures (must be >= 1)
+     * @returns Delay in milliseconds
+     */
+    const calculateBackoffDelay = (count) => {
+        const base = Math.min(failureBackoffMs * failureBackoffFactor ** (count - 1), failureBackoffMaxMs);
+        const jittered = base * (1 + (Math.random() - 0.5) * 2 * failureBackoffJitter);
+        return Math.max(0, jittered);
+    };
+    /**
+     * Check if we're in a backoff period after a failure.
+     * @returns True if still in backoff period
+     */
+    const isInBackoffPeriod = () => {
+        if (backoffDeadline === 0)
+            return false;
+        return Date.now() < backoffDeadline;
+    };
+    /**
+     * Fetch fresh headers from the underlying provider.
+     *
+     * Calls getHeaders() directly rather than refresh() + getHeaders().
+     * The provider's getHeaders() is self-sufficient (fetches a token when
+     * needed), so an explicit refresh() is unnecessary and creates a race
+     * window where invalidate() between the two calls triggers a redundant
+     * token fetch.
+     *
+     * @returns Fresh headers
+     */
+    const fetchHeaders = async () => {
+        try {
+            const headers = await provider.getHeaders();
+            cachedHeaders = headers;
+            cacheExpiry = calculateExpiry(cacheDurationMs);
+            failureCount = 0;
+            backoffDeadline = 0;
+            return headers;
+        }
+        catch (error) {
+            failureCount += 1;
+            backoffDeadline = Date.now() + calculateBackoffDelay(failureCount);
+            throw error;
+        }
+    };
+    const wrapper = {
+        get type() {
+            return provider.type;
+        },
+        async initialize() {
+            await provider.initialize();
+        },
+        async getHeaders() {
+            // Return cached headers if valid
+            if (cachedHeaders && Date.now() < cacheExpiry) {
+                return cachedHeaders;
+            }
+            // If already refreshing, wait for that promise
+            if (refreshPromise) {
+                return refreshPromise;
+            }
+            // Check backoff period - if in backoff, rethrow if no cache
+            if (isInBackoffPeriod()) {
+                if (cachedHeaders) {
+                    // Return stale cache during backoff rather than failing
+                    return cachedHeaders;
+                }
+                // No cache available and in backoff - we must try anyway
+            }
+            // Fetch new headers
+            refreshPromise = fetchHeaders();
+            try {
+                return await refreshPromise;
+            }
+            finally {
+                refreshPromise = null;
+            }
+        },
+        async refresh() {
+            cachedHeaders = null;
+            cacheExpiry = 0;
+            failureCount = 0;
+            backoffDeadline = 0;
+            await provider.refresh();
+        },
+        invalidate() {
+            cachedHeaders = null;
+            cacheExpiry = 0;
+            failureCount = 0;
+            backoffDeadline = 0;
+            provider.invalidate();
+        },
+    };
+    return wrapper;
+}
+//# sourceMappingURL=with-caching.js.map

package/dist/client/auth/decorators/with-caching.js.map

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

package/dist/client/auth/factory.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Factory function for creating JWT AuthProvider instances.
+ * @module client/auth/factory
+ */
+import type { AuthProvider, JwtAuthConfig } from "./types.js";
+/**
+ * Creates a JWT AuthProvider with token caching.
+ * @param config - JWT authentication configuration
+ * @returns Configured AuthProvider instance
+ * @throws {ValidationError} If the configuration is invalid
+ */
+export declare function createAuthProvider(config: JwtAuthConfig): AuthProvider;
+//# sourceMappingURL=factory.d.ts.map

package/dist/client/auth/factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../../../src/client/auth/factory.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAK9D;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,aAAa,GAAG,YAAY,CAatE"}

package/dist/client/auth/factory.js

@@ -0,0 +1,29 @@
+/**
+ * Factory function for creating JWT AuthProvider instances.
+ * @module client/auth/factory
+ */
+import { ValidationError } from "../errors.js";
+import { withCaching } from "./decorators/index.js";
+import { JwtAuthProvider } from "./providers/jwt-auth-provider.js";
+import { JwtAuthConfigSchema } from "./schemas.js";
+/** Default token cache duration for JWT: 1 hour */
+const DEFAULT_TOKEN_CACHE_DURATION_MS = 3600000;
+/**
+ * Creates a JWT AuthProvider with token caching.
+ * @param config - JWT authentication configuration
+ * @returns Configured AuthProvider instance
+ * @throws {ValidationError} If the configuration is invalid
+ */
+export function createAuthProvider(config) {
+    const parseResult = JwtAuthConfigSchema.safeParse(config);
+    if (!parseResult.success) {
+        throw new ValidationError(`Invalid auth configuration: ${parseResult.error.message}`, {
+            issues: parseResult.error.issues,
+        });
+    }
+    const validConfig = parseResult.data;
+    const jwtProvider = new JwtAuthProvider(validConfig);
+    const cacheDurationMs = (validConfig.tokenCacheDuration ?? 3600) * 1000 || DEFAULT_TOKEN_CACHE_DURATION_MS;
+    return withCaching(jwtProvider, { cacheDurationMs });
+}
+//# sourceMappingURL=factory.js.map

package/dist/client/auth/factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.js","sourceRoot":"","sources":["../../../src/client/auth/factory.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACpD,OAAO,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AACnE,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAGnD,mDAAmD;AACnD,MAAM,+BAA+B,GAAG,OAAO,CAAC;AAEhD;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,MAAqB;IACtD,MAAM,WAAW,GAAG,mBAAmB,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IAC1D,IAAI,CAAC,WAAW,CAAC,OAAO,EAAE,CAAC;QACzB,MAAM,IAAI,eAAe,CAAC,+BAA+B,WAAW,CAAC,KAAK,CAAC,OAAO,EAAE,EAAE;YACpF,MAAM,EAAE,WAAW,CAAC,KAAK,CAAC,MAAM;SACjC,CAAC,CAAC;IACL,CAAC;IAED,MAAM,WAAW,GAAG,WAAW,CAAC,IAAI,CAAC;IACrC,MAAM,WAAW,GAAG,IAAI,eAAe,CAAC,WAAW,CAAC,CAAC;IACrD,MAAM,eAAe,GACnB,CAAC,WAAW,CAAC,kBAAkB,IAAI,IAAI,CAAC,GAAG,IAAI,IAAI,+BAA+B,CAAC;IACrF,OAAO,WAAW,CAAC,WAAW,EAAE,EAAE,eAAe,EAAE,CAAC,CAAC;AACvD,CAAC"}