@sharpe-terminal/mcp-server 1.2.0 → 1.4.0

package/README.md

@@ -1,41 +1,24 @@
 # @sharpe-terminal/mcp-server
 
-Model Context Protocol (MCP) server for the Sharpe crypto derivatives and market data API. Enables AI agents (Claude, Cursor, Windsurf, etc.) to query real-time crypto market data including funding rates, futures, arbitrage opportunities, narratives, ecosystems, and more.
+MCP server for [Sharpe Terminal](https://www.sharpe.ai): crypto derivatives
+and market data for AI agents. Funding rates across 32 exchanges, futures
+(open interest, liquidations, basis, long/short), arbitrage scanners,
+correlation, listings, narratives, and more, exposed as Model Context
+Protocol tools.
 
-## Installation
-
-Requires Node.js 18 or later.
-
-### npx (no install)
+## Quick start
 
 ```bash
 npx @sharpe-terminal/mcp-server
 ```
 
-### Global install
+Or add it to Claude:
 
 ```bash
-npm install -g @sharpe-terminal/mcp-server
-sharpe-mcp
+claude mcp add sharpe -- npx -y @sharpe-terminal/mcp-server
 ```
 
-## Configuration
-
-### Environment Variables
-
-| Variable | Required | Default | Description |
-|---|---|---|---|
-| `SHARPE_API_KEY` | No | — | Your Sharpe API key (`sk_live_...`). When set, uses the authenticated `/api/v1/` endpoints with higher rate limits. |
-| `SHARPE_API_URL` | No | `https://www.sharpe.ai` | Base URL for authenticated `/api/v1/*` API requests. |
-| `SHARPE_FREE_URL` | No | `https://www.sharpe.ai` | Base URL for free `/api/*` fallback requests. |
-
-Without an API key, the server falls back to free public endpoints when a matching public route exists. Authenticated-only `/api/v1/*` tools require `SHARPE_API_KEY`.
-
-Custom base URLs must use `https://`, except `http://localhost`/`127.0.0.1`/`::1` for local development. The server refuses API redirects so credentials are not forwarded to unexpected hosts.
-
-### Claude Desktop
-
-Add to your `claude_desktop_config.json` (usually at `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS or `%APPDATA%\Claude\claude_desktop_config.json` on Windows):
+Generic MCP client config:
 
 ```json
 {
@@ -43,151 +26,68 @@ Add to your `claude_desktop_config.json` (usually at `~/Library/Application Supp
     "sharpe": {
       "command": "npx",
       "args": ["-y", "@sharpe-terminal/mcp-server"],
-      "env": {
-        "SHARPE_API_KEY": "sk_live_your_key_here"
-      }
+      "env": { "SHARPE_API_KEY": "sk_live_..." }
     }
   }
 }
 ```
 
-### Claude Code
+### Hosted endpoint (no install)
+
+The same server runs at `https://www.sharpe.ai/api/mcp` (Streamable HTTP).
+Clients that take a URL need nothing installed; send a key as a header for
+the authenticated routes:
 
 ```bash
-claude mcp add sharpe -- npx -y @sharpe-terminal/mcp-server
+claude mcp add --transport http sharpe-mcp https://www.sharpe.ai/api/mcp \
+  --header "Authorization: Bearer sk_live_..."
 ```
 
-Or with an API key:
+## Configuration
 
-```bash
-SHARPE_API_KEY=sk_live_your_key_here claude mcp add sharpe -- npx -y @sharpe-terminal/mcp-server
-```
+| Env var | Required | Purpose |
+| --- | --- | --- |
+| `SHARPE_API_KEY` | No | v1 API key (higher limits). Without it, tools fall back to the free public endpoints. |
+| `SHARPE_API_URL` | No | Override the authenticated API base (HTTPS required outside localhost). |
+| `SHARPE_FREE_URL` | No | Override the free API base (HTTPS required outside localhost). |
 
-### Cursor
+Get a key at [sharpe.ai/dashboard/api-keys](https://www.sharpe.ai/dashboard/api-keys). Redirects
+are never followed, and keys are never forwarded across hosts.
 
-Add to your `.cursor/mcp.json`:
+## What you get
 
-```json
-{
-  "mcpServers": {
-    "sharpe": {
-      "command": "npx",
-      "args": ["-y", "@sharpe-terminal/mcp-server"],
-      "env": {
-        "SHARPE_API_KEY": "sk_live_your_key_here"
-      }
-    }
-  }
-}
-```
+- 37 endpoint tools: funding rates (current / accumulated / per-coin
+  history), funding settlement (dollar value actually paid, long/short
+  split, per-window totals), futures charts, arbitrage (spot-perp,
+  cross-exchange, basis, calendar spread, carry), correlation matrix,
+  market overview, listings, narratives, ecosystems, memecoins, gem finder,
+  rug check, token scanner, stablecoins, news, and more.
+- 3 composite workflows: `analyze_coin`, `market_briefing`,
+  `find_opportunities` fan out across several endpoints and return a
+  formatted briefing.
+- 4 resources and 2 prompts: chart-id catalogs and guided workflows.
 
-### Local development (from source)
+Paginated endpoints (`get_funding_rates`, `get_gem_finder`) return a
+`pagination` block with the continuation cursor when more rows exist.
 
-```bash
-cd packages/mcp-server
-npm install
-npm run build
-node dist/index.js
-```
+Large responses are truncated to protect the model context window; the
+payload marks `truncated: true` with the total count when that happens.
+
+## Data freshness
+
+Current funding rates refresh every 5 minutes; accumulated funding keeps a
+30-minute refresh, and funding history rows land per settlement. Futures
+datasets refresh every 10 minutes to 6 hours depending on the metric;
+narrative and ecosystem data refreshes every 2 hours. Responses carry the
+API's freshness metadata.
+
+## Links
+
+- API docs: https://www.sharpe.ai/docs
+- OpenAPI spec: https://www.sharpe.ai/openapi.json
+- MCP guide: https://www.sharpe.ai/docs/mcp-server
+- Python server + CLI source:
+  [`packages/mcp-server-python`](../mcp-server-python). Its first PyPI release
+  is pending; do not use `pip` or `uvx` until the package exists on PyPI.
 
-## Available Tools
-
-The TypeScript package exposes 41 tools: 38 endpoint tools plus 3 composite workflows (`analyze_coin`, `market_briefing`, `find_opportunities`). The Python `sharpe-terminal-mcp` package mirrors this surface and is the primary distribution for the companion CLI.
-
-All tools are read-only market-data calls. They advertise MCP annotations for `readOnlyHint`, `destructiveHint=false`, `idempotentHint`, and `openWorldHint`. Endpoint tools return both `structuredContent` (`{ "result": ... }`) and text JSON for older clients. Composite workflow tools return `{ "report": "..." }` in `structuredContent` plus the same markdown report in text content.
-
-Large list responses are capped at 200 rows before they are returned to the MCP client. Truncated payloads include `truncated`, `total`, and `showing` fields.
-
-Release checklist and cross-package synchronization notes live in [`../../docs/release-packages.md`](../../docs/release-packages.md).
-
-### Composite Workflows
-
-| Tool | Description |
-|---|---|
-| `analyze_coin` | Single-coin analysis combining funding, futures OI, and prediction data |
-| `market_briefing` | Market overview, narrative leaders, and funding highlights in one briefing |
-| `find_opportunities` | Funding-rate and arbitrage opportunity scan across multiple sources |
-
-### Derivatives
-
-| Tool | Description |
-|---|---|
-| `get_funding_rates` | Perpetual funding rates across exchanges (current, accumulated, or historical) |
-| `get_futures_data` | Futures chart data: OI, volume, liquidations, long/short ratios, basis, term structure |
-| `get_futures_coins` | List of coins with futures data and exchange capability flags |
-| `get_derivatives_overview` | Market-wide derivatives snapshot: total OI, weighted funding, top coins, and exchange counts |
-
-### Market Data
-
-| Tool | Description |
-|---|---|
-| `get_heatmap` | Market heatmap by coins, narratives, or ecosystems |
-| `get_correlation_matrix` | Price correlation matrix for portfolio analysis |
-| `get_market_overview` | Total market cap, BTC dominance, top gainers/losers, trending coins |
-| `get_price_prediction` | ML-based price predictions with confidence intervals |
-| `search_market_cap` | Search coins by name or ticker with market cap data |
-| `get_news` | Aggregated crypto news with category and coin filters |
-| `get_curated_news` | Curated crypto news highlights |
-| `get_gem_finder` | Curated low-cap, high-potential token discovery |
-| `get_stablecoins` | Stablecoin overview, detail, peg, chain supply, and yield data |
-| `get_mindshare` | Narrative mindshare, token-level attention, and historical snapshots |
-| `get_web_traffic` | Attention rankings, search trends, and social/developer snapshots |
-| `get_katana` | Katana Network TVL, token, holder, sentiment, pool, and ecosystem analytics |
-
-### Screener
-
-| Tool | Description |
-|---|---|
-| `get_dexscreener_data` | Live DEX pair screening by category, network, or search phrase |
-| `get_dexscreener_security` | Token contract security signals for DEX Screener tokens |
-| `get_token_scanner` | Read-only hot token, new runner, alpha drop, AI token, and top-new scans |
-| `get_rug_check_security` | Token contract and liquidity risk signals |
-| `get_rug_check_trending` | Trending tokens suitable for rug-check review |
-| `get_insider_selling` | Insider selling pressure and holder-quality risk signals |
-| `get_pump_dump` | Pump-and-dump manipulation risk signals |
-
-### Arbitrage
-
-| Tool | Description |
-|---|---|
-| `get_arbitrage_spot_perp` | Spot-perpetual funding rate arbitrage opportunities |
-| `get_arbitrage_cross_exchange` | Cross-exchange price discrepancy arbitrage |
-| `get_arbitrage_dated_futures_basis` | Spot-futures cash-and-carry basis rows |
-| `get_arbitrage_futures_calendar_spread` | Near-versus-far dated futures curve rows |
-| `get_arbitrage_perp_dated_carry` | Perp funding versus dated futures carry rows |
-| `get_arbitrage_cex_spot_transfer` | CEX spot-transfer rows with network, fee, depth, and slippage checks |
-
-### Categories
-
-| Tool | Description |
-|---|---|
-| `get_narratives` | Narrative-level data: L1, L2, DeFi, AI Agents, DePIN, RWA, etc. |
-| `get_ecosystems` | Ecosystem-level data: Ethereum, Solana, Arbitrum, Base, etc. with TVL |
-| `get_memecoins` | Memecoin narrative data: Dog, Cat, Frog, AI, Solana, Base, Pump.fun, etc. |
-| `get_memecoin_launches` | Recently launched memecoin pairs screened by age, liquidity, volume, and transactions |
-| `get_exchange_listings` | New Listings aggregate activity by narrative and venue |
-| `get_recent_listings` | Recent token listings feed |
-| `get_listing_events` | Canonical listing lifecycle events with source confidence |
-| `get_listing_exchanges` | Listing connector coverage and parser status |
-
-### System
-
-| Tool | Description |
-|---|---|
-| `get_api_coverage` | Available data products, exchanges, timeframes, and chart coverage |
-
-## Example Prompts
-
-Once connected, you can ask your AI agent things like:
-
-- "What are the current BTC funding rates across exchanges?"
-- "Show me the top spot-perp arbitrage opportunities"
-- "What's the correlation between BTC, ETH, and SOL over the last 90 days?"
-- "Show me the DeFi narrative performance data"
-- "Search for Solana in the market cap tracker"
-- "What are the latest crypto news about Bitcoin?"
-- "Get the futures open interest chart for ETH over the last month"
-
-## License
-
-MIT
+MIT © Sharpe Terminal

package/dist/api-client.d.ts

@@ -5,9 +5,26 @@ export interface ApiClientOptions {
     fallbackBaseUrl: string;
     userAgent: string;
     fetchImpl?: typeof fetch;
+    /** Appended to a keyless 401: how this caller supplies a key. */
+    missingKeyHint?: string;
+    /** Test seam for retry backoff. */
+    sleep?: (ms: number) => Promise<void>;
 }
+/** How long to wait before retrying, or null when the failure is final. */
+export declare function retryDelayMs(response: Response | null): number | null;
+/**
+ * The error an agent reads: status plus the problem detail, suggested action
+ * and request id from the API's problem+json body, rather than the raw JSON.
+ */
+export declare function describeApiFailure(response: Response, body: string, hint?: string): string;
 export declare function normalizeBaseUrl(base: string): string;
 export declare function redactUrl(input: string): string;
 export declare function buildUrl(base: string, path: string, params: Record<string, unknown>): string;
+/** `{ cursor, has_more, total }` from header-only pagination, or null when absent. */
+export declare function headerPagination(headers: Headers): {
+    cursor: string | null;
+    has_more: boolean;
+    total: number | null;
+} | null;
 export declare function createApiCaller(options: ApiClientOptions): ApiCaller;
 //# sourceMappingURL=api-client.d.ts.map

package/dist/api-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api-client.d.ts","sourceRoot":"","sources":["../src/api-client.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,SAAS,GAAG,CACtB,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC1B,OAAO,CAAC,OAAO,CAAC,CAAC;AAEtB,MAAM,WAAW,gBAAgB;IAC/B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAsCrD;AAED,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAS/C;AAED,wBAAgB,QAAQ,CACtB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,MAAM,CAQR;AAED,wBAAgB,eAAe,CAAC,OAAO,EAAE,gBAAgB,GAAG,SAAS,CAgEpE"}
+{"version":3,"file":"api-client.d.ts","sourceRoot":"","sources":["../src/api-client.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,SAAS,GAAG,CACtB,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC1B,OAAO,CAAC,OAAO,CAAC,CAAC;AAEtB,MAAM,WAAW,gBAAgB;IAC/B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,iEAAiE;IACjE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,mCAAmC;IACnC,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACvC;AAuBD,2EAA2E;AAC3E,wBAAgB,YAAY,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI,GAAG,MAAM,GAAG,IAAI,CAWrE;AASD;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,QAAQ,EAClB,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE,MAAM,GACZ,MAAM,CA+BR;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAsCrD;AAED,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAS/C;AAED,wBAAgB,QAAQ,CACtB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,MAAM,CAQR;AAED,sFAAsF;AACtF,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,GAAG;IAClD,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,QAAQ,EAAE,OAAO,CAAC;IAClB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB,GAAG,IAAI,CAUP;AAED,wBAAgB,eAAe,CAAC,OAAO,EAAE,gBAAgB,GAAG,SAAS,CAoHpE"}

package/dist/api-client.js

@@ -1,4 +1,76 @@
 const LOCAL_HTTP_HOSTS = new Set(["localhost", "127.0.0.1", "::1", "[::1]"]);
+const DEFAULT_MISSING_KEY_HINT = "This tool needs an API key: set SHARPE_API_KEY (the free tier works, https://www.sharpe.ai/docs/authentication).";
+/** One retry: transient failures usually clear within a second. */
+const MAX_ATTEMPTS = 2;
+const RETRYABLE_STATUSES = new Set([502, 503, 504]);
+/**
+ * A 429 is retried only when the API says the window reopens this soon. A
+ * monthly-quota 429 carries a Retry-After of days and fails straight away.
+ */
+const MAX_RATE_LIMIT_WAIT_MS = 10_000;
+function retryAfterMs(response) {
+    const value = response.headers.get("retry-after");
+    if (!value)
+        return null;
+    const seconds = Number(value);
+    if (Number.isFinite(seconds))
+        return Math.max(0, seconds * 1000);
+    const date = Date.parse(value);
+    return Number.isFinite(date) ? Math.max(0, date - Date.now()) : null;
+}
+/** How long to wait before retrying, or null when the failure is final. */
+export function retryDelayMs(response) {
+    // Network failure before any response (reset, DNS): retry shortly.
+    if (response === null)
+        return 500;
+    if (RETRYABLE_STATUSES.has(response.status)) {
+        return Math.min(retryAfterMs(response) ?? 500, MAX_RATE_LIMIT_WAIT_MS);
+    }
+    if (response.status === 429) {
+        const wait = retryAfterMs(response);
+        return wait != null && wait <= MAX_RATE_LIMIT_WAIT_MS ? wait : null;
+    }
+    return null;
+}
+function isTimeout(error) {
+    return (error instanceof Error &&
+        (error.name === "TimeoutError" || error.name === "AbortError"));
+}
+/**
+ * The error an agent reads: status plus the problem detail, suggested action
+ * and request id from the API's problem+json body, rather than the raw JSON.
+ */
+export function describeApiFailure(response, body, hint) {
+    let detail = body.slice(0, 500);
+    try {
+        const problem = JSON.parse(body);
+        const text = [problem.detail, problem.error, problem.message].find((value) => typeof value === "string" && value !== "");
+        if (text) {
+            detail = [
+                text,
+                typeof problem.suggested_action === "string"
+                    ? problem.suggested_action
+                    : null,
+                typeof problem.request_id === "string"
+                    ? `(request_id ${problem.request_id})`
+                    : null,
+            ]
+                .filter(Boolean)
+                .join(" ");
+        }
+    }
+    catch {
+        // Not JSON: keep the raw (clipped) body.
+    }
+    const retryAfter = response.headers.get("retry-after");
+    return [
+        `API returned ${response.status} ${response.statusText}: ${detail}`,
+        retryAfter ? `Retry after ${retryAfter}s.` : null,
+        hint ?? null,
+    ]
+        .filter(Boolean)
+        .join(" ");
+}
 export function normalizeBaseUrl(base) {
     const normalized = base.trim().replace(/\/+$/, "");
     if (!normalized)
@@ -54,11 +126,26 @@ export function buildUrl(base, path, params) {
     }
     return url.toString();
 }
+/** `{ cursor, has_more, total }` from header-only pagination, or null when absent. */
+export function headerPagination(headers) {
+    const cursor = headers.get("x-next-cursor");
+    const totalHeader = headers.get("x-total-count");
+    if (cursor == null && totalHeader == null)
+        return null;
+    const total = totalHeader == null ? Number.NaN : Number(totalHeader);
+    return {
+        cursor: cursor || null,
+        has_more: Boolean(cursor),
+        total: Number.isFinite(total) ? total : null,
+    };
+}
 export function createApiCaller(options) {
     const apiKey = (options.apiKey ?? "").trim();
     const apiBaseUrl = normalizeBaseUrl(options.apiBaseUrl);
     const fallbackBaseUrl = normalizeBaseUrl(options.fallbackBaseUrl);
     const fetchImpl = options.fetchImpl ?? fetch;
+    const sleep = options.sleep ??
+        ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
     return async function callApi(apiPath, fallbackPath, args) {
         const useAuthenticatedApi = apiKey.length > 0;
         const base = useAuthenticatedApi ? apiBaseUrl : fallbackBaseUrl;
@@ -71,19 +158,48 @@ export function createApiCaller(options) {
         if (useAuthenticatedApi) {
             headers.Authorization = `Bearer ${apiKey}`;
         }
-        const response = await fetchImpl(url, {
-            method: "GET",
-            headers,
-            redirect: "manual",
-            signal: AbortSignal.timeout(30_000),
-        });
-        if (response.status >= 300 && response.status < 400) {
+        let response;
+        for (let attempt = 1;; attempt += 1) {
+            let attemptResponse = null;
+            try {
+                attemptResponse = await fetchImpl(url, {
+                    method: "GET",
+                    headers,
+                    redirect: "manual",
+                    signal: AbortSignal.timeout(30_000),
+                });
+            }
+            catch (error) {
+                // A timeout already cost the caller 30s; only fast failures retry.
+                if (attempt >= MAX_ATTEMPTS || isTimeout(error))
+                    throw error;
+            }
+            const delay = attempt < MAX_ATTEMPTS ? retryDelayMs(attemptResponse) : null;
+            if (attemptResponse && delay === null) {
+                response = attemptResponse;
+                break;
+            }
+            // Release the discarded attempt's connection before retrying.
+            await attemptResponse?.body?.cancel().catch(() => undefined);
+            await sleep(delay ?? 0);
+        }
+        // 304 Not Modified is excluded: it is a cache-validation response, not a
+        // redirect, carries no Location, and never forwards credentials anywhere.
+        // This client sends no If-None-Match today, so a 304 is unexpected here;
+        // let it fall through to the generic !ok handling below instead of
+        // misreporting it as a credential-protecting redirect refusal.
+        if (response.status >= 300 &&
+            response.status < 400 &&
+            response.status !== 304) {
             const location = response.headers.get("location") ?? "unknown";
             throw new Error(`Sharpe API redirected ${redactUrl(url)} to ${location}. Refusing to follow redirects to protect credentials; set SHARPE_API_URL/SHARPE_FREE_URL to the canonical HTTPS host.`);
         }
         if (!response.ok) {
             const body = await response.text().catch(() => "");
-            throw new Error(`API returned ${response.status} ${response.statusText}: ${body.slice(0, 500)}`);
+            const hint = response.status === 401 && !useAuthenticatedApi
+                ? (options.missingKeyHint ?? DEFAULT_MISSING_KEY_HINT)
+                : undefined;
+            throw new Error(describeApiFailure(response, body, hint));
         }
         let data;
         try {
@@ -92,12 +208,31 @@ export function createApiCaller(options) {
         catch {
             throw new Error(`API returned invalid JSON for ${apiPath}`);
         }
+        // The free funding book keeps its body a bare array and carries the page
+        // cursor only in X-Next-Cursor / X-Total-Count headers. Wrap it in the v1
+        // pagination shape so the runtime reattaches the cursor instead of
+        // silently dropping it (2026-09-24 audit).
+        if (Array.isArray(data)) {
+            const pagination = headerPagination(response.headers);
+            return pagination ? { data, pagination } : data;
+        }
         if (data &&
             typeof data === "object" &&
             !Array.isArray(data) &&
             "data" in data &&
             "meta" in data) {
-            return data.data;
+            const envelope = data;
+            // Sibling fields riding alongside `data`/`meta` -- a pagination cursor,
+            // or an aggregate block like funding/settlement's `totals` -- carry
+            // state the caller needs. Unwrapping to `.data` alone silently
+            // discarded them: paginated results could never be continued
+            // (2026-07-27 audit), and an aggregate would have to be recomputed
+            // client-side from a truncated page instead of read once.
+            const { data: inner, meta, ...siblings } = envelope;
+            void meta;
+            return Object.keys(siblings).length > 0
+                ? { data: inner, ...siblings }
+                : inner;
         }
         return data;
     };

package/dist/api-client.js.map

@@ -1 +1 @@
-{"version":3,"file":"api-client.js","sourceRoot":"","sources":["../src/api-client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"api-client.js","sourceRoot":"","sources":["../src/api-client.ts"],"names":[],"mappings":"AAAA,MAAM,gBAAgB,GAAG,IAAI,GAAG,CAAC,CAAC,WAAW,EAAE,WAAW,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC;AAoB7E,MAAM,wBAAwB,GAC5B,kHAAkH,CAAC;AAErH,mEAAmE;AACnE,MAAM,YAAY,GAAG,CAAC,CAAC;AACvB,MAAM,kBAAkB,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC;AACpD;;;GAGG;AACH,MAAM,sBAAsB,GAAG,MAAM,CAAC;AAEtC,SAAS,YAAY,CAAC,QAAkB;IACtC,MAAM,KAAK,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;IAClD,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IACxB,MAAM,OAAO,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;IAC9B,IAAI,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC;QAAE,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC,CAAC;IACjE,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAC/B,OAAO,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AACvE,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,YAAY,CAAC,QAAyB;IACpD,mEAAmE;IACnE,IAAI,QAAQ,KAAK,IAAI;QAAE,OAAO,GAAG,CAAC;IAClC,IAAI,kBAAkB,CAAC,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;QAC5C,OAAO,IAAI,CAAC,GAAG,CAAC,YAAY,CAAC,QAAQ,CAAC,IAAI,GAAG,EAAE,sBAAsB,CAAC,CAAC;IACzE,CAAC;IACD,IAAI,QAAQ,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;QAC5B,MAAM,IAAI,GAAG,YAAY,CAAC,QAAQ,CAAC,CAAC;QACpC,OAAO,IAAI,IAAI,IAAI,IAAI,IAAI,IAAI,sBAAsB,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;IACtE,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,SAAS,CAAC,KAAc;IAC/B,OAAO,CACL,KAAK,YAAY,KAAK;QACtB,CAAC,KAAK,CAAC,IAAI,KAAK,cAAc,IAAI,KAAK,CAAC,IAAI,KAAK,YAAY,CAAC,CAC/D,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAChC,QAAkB,EAClB,IAAY,EACZ,IAAa;IAEb,IAAI,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IAChC,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAA4B,CAAC;QAC5D,MAAM,IAAI,GAAG,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC,IAAI,CAChE,CAAC,KAAK,EAAmB,EAAE,CAAC,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,EAAE,CACtE,CAAC;QACF,IAAI,IAAI,EAAE,CAAC;YACT,MAAM,GAAG;gBACP,IAAI;gBACJ,OAAO,OAAO,CAAC,gBAAgB,KAAK,QAAQ;oBAC1C,CAAC,CAAC,OAAO,CAAC,gBAAgB;oBAC1B,CAAC,CAAC,IAAI;gBACR,OAAO,OAAO,CAAC,UAAU,KAAK,QAAQ;oBACpC,CAAC,CAAC,eAAe,OAAO,CAAC,UAAU,GAAG;oBACtC,CAAC,CAAC,IAAI;aACT;iBACE,MAAM,CAAC,OAAO,CAAC;iBACf,IAAI,CAAC,GAAG,CAAC,CAAC;QACf,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,yCAAyC;IAC3C,CAAC;IACD,MAAM,UAAU,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;IACvD,OAAO;QACL,gBAAgB,QAAQ,CAAC,MAAM,IAAI,QAAQ,CAAC,UAAU,KAAK,MAAM,EAAE;QACnE,UAAU,CAAC,CAAC,CAAC,eAAe,UAAU,IAAI,CAAC,CAAC,CAAC,IAAI;QACjD,IAAI,IAAI,IAAI;KACb;SACE,MAAM,CAAC,OAAO,CAAC;SACf,IAAI,CAAC,GAAG,CAAC,CAAC;AACf,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,IAAY;IAC3C,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IACnD,IAAI,CAAC,UAAU;QAAE,MAAM,IAAI,KAAK,CAAC,4BAA4B,CAAC,CAAC;IAE/D,IAAI,GAAQ,CAAC;IACb,IAAI,CAAC;QACH,GAAG,GAAG,IAAI,GAAG,CAAC,UAAU,CAAC,CAAC;IAC5B,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,KAAK,CAAC,0CAA0C,CAAC,CAAC;IAC9D,CAAC;IAED,IAAI,CAAC,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC;QAC7D,MAAM,IAAI,KAAK,CAAC,0CAA0C,CAAC,CAAC;IAC9D,CAAC;IACD,IAAI,GAAG,CAAC,QAAQ,IAAI,GAAG,CAAC,QAAQ,EAAE,CAAC;QACjC,MAAM,IAAI,KAAK,CAAC,uCAAuC,CAAC,CAAC;IAC3D,CAAC;IACD,IAAI,GAAG,CAAC,MAAM,IAAI,GAAG,CAAC,IAAI,EAAE,CAAC;QAC3B,MAAM,IAAI,KAAK,CAAC,sDAAsD,CAAC,CAAC;IAC1E,CAAC;IACD,IAAI,GAAG,CAAC,QAAQ,KAAK,OAAO,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;QACpE,MAAM,IAAI,KAAK,CACb,0GAA0G,CAC3G,CAAC;IACJ,CAAC;IAED,IAAI,IAAI,GAAG,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IAC5C,KAAK,MAAM,MAAM,IAAI,CAAC,SAAS,EAAE,MAAM,CAAC,EAAE,CAAC;QACzC,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;YAC1B,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;YACrC,MAAM;QACR,CAAC;IACH,CAAC;IAED,GAAG,CAAC,QAAQ,GAAG,IAAI,IAAI,GAAG,CAAC;IAC3B,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC;IAChB,GAAG,CAAC,IAAI,GAAG,EAAE,CAAC;IACd,OAAO,GAAG,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;AAC3C,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,KAAa;IACrC,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC;QAC3B,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC;QAChB,GAAG,CAAC,IAAI,GAAG,EAAE,CAAC;QACd,OAAO,GAAG,CAAC,QAAQ,EAAE,CAAC;IACxB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED,MAAM,UAAU,QAAQ,CACtB,IAAY,EACZ,IAAY,EACZ,MAA+B;IAE/B,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IAChC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAClD,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,EAAE,EAAE,CAAC;YAC1D,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;QAC3C,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC,QAAQ,EAAE,CAAC;AACxB,CAAC;AAED,sFAAsF;AACtF,MAAM,UAAU,gBAAgB,CAAC,OAAgB;IAK/C,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC;IAC5C,MAAM,WAAW,GAAG,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC;IACjD,IAAI,MAAM,IAAI,IAAI,IAAI,WAAW,IAAI,IAAI;QAAE,OAAO,IAAI,CAAC;IACvD,MAAM,KAAK,GAAG,WAAW,IAAI,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;IACrE,OAAO;QACL,MAAM,EAAE,MAAM,IAAI,IAAI;QACtB,QAAQ,EAAE,OAAO,CAAC,MAAM,CAAC;QACzB,KAAK,EAAE,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI;KAC7C,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,OAAyB;IACvD,MAAM,MAAM,GAAG,CAAC,OAAO,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IAC7C,MAAM,UAAU,GAAG,gBAAgB,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;IACxD,MAAM,eAAe,GAAG,gBAAgB,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC;IAClE,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,KAAK,CAAC;IAC7C,MAAM,KAAK,GACT,OAAO,CAAC,KAAK;QACb,CAAC,CAAC,EAAU,EAAE,EAAE,CAAC,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC;IAE5E,OAAO,KAAK,UAAU,OAAO,CAC3B,OAAe,EACf,YAAoB,EACpB,IAA6B;QAE7B,MAAM,mBAAmB,GAAG,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC;QAC9C,MAAM,IAAI,GAAG,mBAAmB,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,eAAe,CAAC;QAChE,MAAM,IAAI,GAAG,mBAAmB,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,YAAY,CAAC;QAC1D,MAAM,GAAG,GAAG,QAAQ,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;QAEvC,MAAM,OAAO,GAA2B;YACtC,MAAM,EAAE,kBAAkB;YAC1B,YAAY,EAAE,OAAO,CAAC,SAAS;SAChC,CAAC;QAEF,IAAI,mBAAmB,EAAE,CAAC;YACxB,OAAO,CAAC,aAAa,GAAG,UAAU,MAAM,EAAE,CAAC;QAC7C,CAAC;QAED,IAAI,QAAkB,CAAC;QACvB,KAAK,IAAI,OAAO,GAAG,CAAC,GAAI,OAAO,IAAI,CAAC,EAAE,CAAC;YACrC,IAAI,eAAe,GAAoB,IAAI,CAAC;YAC5C,IAAI,CAAC;gBACH,eAAe,GAAG,MAAM,SAAS,CAAC,GAAG,EAAE;oBACrC,MAAM,EAAE,KAAK;oBACb,OAAO;oBACP,QAAQ,EAAE,QAAQ;oBAClB,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,MAAM,CAAC;iBACpC,CAAC,CAAC;YACL,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,mEAAmE;gBACnE,IAAI,OAAO,IAAI,YAAY,IAAI,SAAS,CAAC,KAAK,CAAC;oBAAE,MAAM,KAAK,CAAC;YAC/D,CAAC;YACD,MAAM,KAAK,GACT,OAAO,GAAG,YAAY,CAAC,CAAC,CAAC,YAAY,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;YAChE,IAAI,eAAe,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;gBACtC,QAAQ,GAAG,eAAe,CAAC;gBAC3B,MAAM;YACR,CAAC;YACD,8DAA8D;YAC9D,MAAM,eAAe,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;YAC7D,MAAM,KAAK,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC;QAC1B,CAAC;QAED,yEAAyE;QACzE,0EAA0E;QAC1E,yEAAyE;QACzE,mEAAmE;QACnE,+DAA+D;QAC/D,IACE,QAAQ,CAAC,MAAM,IAAI,GAAG;YACtB,QAAQ,CAAC,MAAM,GAAG,GAAG;YACrB,QAAQ,CAAC,MAAM,KAAK,GAAG,EACvB,CAAC;YACD,MAAM,QAAQ,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,SAAS,CAAC;YAC/D,MAAM,IAAI,KAAK,CACb,yBAAyB,SAAS,CAAC,GAAG,CAAC,OAAO,QAAQ,wHAAwH,CAC/K,CAAC;QACJ,CAAC;QAED,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;YACjB,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC;YACnD,MAAM,IAAI,GACR,QAAQ,CAAC,MAAM,KAAK,GAAG,IAAI,CAAC,mBAAmB;gBAC7C,CAAC,CAAC,CAAC,OAAO,CAAC,cAAc,IAAI,wBAAwB,CAAC;gBACtD,CAAC,CAAC,SAAS,CAAC;YAChB,MAAM,IAAI,KAAK,CAAC,kBAAkB,CAAC,QAAQ,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC;QAC5D,CAAC;QAED,IAAI,IAAa,CAAC;QAClB,IAAI,CAAC;YACH,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;QAC/B,CAAC;QAAC,MAAM,CAAC;YACP,MAAM,IAAI,KAAK,CAAC,iCAAiC,OAAO,EAAE,CAAC,CAAC;QAC9D,CAAC;QAED,yEAAyE;QACzE,0EAA0E;QAC1E,mEAAmE;QACnE,2CAA2C;QAC3C,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;YACxB,MAAM,UAAU,GAAG,gBAAgB,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;YACtD,OAAO,UAAU,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;QAClD,CAAC;QAED,IACE,IAAI;YACJ,OAAO,IAAI,KAAK,QAAQ;YACxB,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC;YACpB,MAAM,IAAI,IAAI;YACd,MAAM,IAAI,IAAI,EACd,CAAC;YACD,MAAM,QAAQ,GAAG,IAA+B,CAAC;YACjD,wEAAwE;YACxE,oEAAoE;YACpE,+DAA+D;YAC/D,6DAA6D;YAC7D,mEAAmE;YACnE,0DAA0D;YAC1D,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,QAAQ,EAAE,GAAG,QAAQ,CAAC;YACpD,KAAK,IAAI,CAAC;YACV,OAAO,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,MAAM,GAAG,CAAC;gBACrC,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,QAAQ,EAAE;gBAC9B,CAAC,CAAC,KAAK,CAAC;QACZ,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC,CAAC;AACJ,CAAC"}

package/dist/composite-tools.d.ts

@@ -6,7 +6,71 @@
 export declare function fmtUsd(value: number | null | undefined): string;
 export declare function fmtPct(value: number | null | undefined): string;
 export declare function fmtRate(value: number | null | undefined): string;
+/**
+ * A funding row's own settlement interval. Returns null rather than a default
+ * when the venue publishes none — see src/products/funding-rate/lib/
+ * CALCULATIONS.md: a stored rate is never implicitly an 8-hour rate.
+ */
+export declare function intervalHours(r: Record<string, unknown>): number | null;
+/** APR for one observation: `rate x (8760 / interval_hours)`. */
+export declare function aprVal(r: Record<string, unknown>): number;
+/**
+ * Minimum open interest (USD) for a market to rank in market_briefing and
+ * find_opportunities, and the per-leg OI and volume floor sent to the
+ * cross-exchange scanner. Without it every extreme was a dust market (ESIM
+ * on KuCoin: $33K of OI at -16,862% APR, 2026-09-24 audit). Unknown OI fails
+ * the floor, the same rule the cross-exchange API applies.
+ */
+export declare const LIQUIDITY_FLOOR_USD = 1000000;
+/** FUNDING_RATE_FRESHNESS_SLA_SECONDS in src/products/funding-rate/lib/freshness.ts. */
+export declare const FUNDING_FRESHNESS_SLA_MS: number;
+/**
+ * A funding row past its freshness SLA. The free endpoint serves stale rows
+ * flagged `is_stale: true` rather than dropping them, so rankings skip them;
+ * a row without the flag is judged from its `updated_at`.
+ */
+export declare function isStaleRow(row: Record<string, unknown>, nowMs?: number): boolean;
+/** A venue whose latest reading trails the newest by more than this is not current OI. */
+export declare const OI_FRESHNESS_WINDOW_MS: number;
+interface VenueOi {
+    exchange: string;
+    value: number;
+    at: number;
+}
+/**
+ * Venues the API names in `openInterestExcludedVenues`: their rows are
+ * shown per venue but never summed (MEXC, whose figure moves 7.00x its own
+ * trade flow), keyed to the reason the payload gives.
+ */
+export declare function excludedOiVenues(payload: unknown): Map<string, string>;
+/**
+ * Each venue's latest open-interest reading, split into venues that are
+ * current (within OI_FRESHNESS_WINDOW_MS of the newest reading), venues
+ * that stopped reporting, and venues the API excludes from totals. Totals
+ * sum every current venue: summing only the ten listed understated BTC by
+ * 9.4% (2026-09-24 audit).
+ */
+export declare function summarizeVenueOi(rows: unknown[], excludedVenues?: ReadonlyMap<string, string>): {
+    current: VenueOi[];
+    stale: VenueOi[];
+    excluded: VenueOi[];
+};
 type ApiCaller = (apiPath: string, fallbackPath: string, args: Record<string, unknown>) => Promise<unknown>;
+/**
+ * Find the prediction row for a ticker in the endpoint's own coverage list.
+ *
+ * The price-prediction endpoint is keyed by CoinGecko slug ("bitcoin",
+ * "avalanche-2", "matic-network"), never by ticker, and a lowercased ticker is
+ * not a slug. Guessing one either 404s or — far worse — resolves to whichever
+ * unrelated asset happens to own that slug, and tickers are shared across
+ * thousands of assets in this dataset. So the guess is a silent wrong-coin
+ * risk, never a convenience: it is resolve-or-say-so here.
+ *
+ * The list response (`GET .../price-prediction/data` with no `coin`) carries
+ * both the ticker (`coin`) and the `slug` for every covered asset, so an exact
+ * ticker match against it is the endpoint's own documented contract.
+ */
+export declare function findPredictionRow(payload: unknown, ticker: string): Record<string, unknown> | null;
 export declare function analyzeCoin(callApi: ApiCaller, coin: string): Promise<string>;
 export declare function marketBriefing(callApi: ApiCaller): Promise<string>;
 export declare function findOpportunities(callApi: ApiCaller): Promise<string>;

package/dist/composite-tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"composite-tools.d.ts","sourceRoot":"","sources":["../src/composite-tools.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,wBAAgB,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAW/D;AAED,wBAAgB,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAG/D;AAED,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAGhE;AAgBD,KAAK,SAAS,GAAG,CACf,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC1B,OAAO,CAAC,OAAO,CAAC,CAAC;AAuCtB,wBAAsB,WAAW,CAC/B,OAAO,EAAE,SAAS,EAClB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,MAAM,CAAC,CAgNjB;AAID,wBAAsB,cAAc,CAAC,OAAO,EAAE,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,CA6LxE;AAID,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,CAiM3E"}
+{"version":3,"file":"composite-tools.d.ts","sourceRoot":"","sources":["../src/composite-tools.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAOH,wBAAgB,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAW/D;AAED,wBAAgB,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAG/D;AAED,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAGhE;AAID;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,GAAG,IAAI,CAGvE;AAMD,iEAAiE;AACjE,wBAAgB,MAAM,CAAC,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAGzD;AAED;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,UAAY,CAAC;AAM7C,wFAAwF;AACxF,eAAO,MAAM,wBAAwB,QAAiB,CAAC;AAEvD;;;;GAIG;AACH,wBAAgB,UAAU,CACxB,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,KAAK,SAAa,GACjB,OAAO,CAMT;AAuCD,0FAA0F;AAC1F,eAAO,MAAM,sBAAsB,QAAqB,CAAC;AAEzD,UAAU,OAAO;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,EAAE,EAAE,MAAM,CAAC;CACZ;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAetE;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,OAAO,EAAE,EACf,cAAc,GAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAa,GACtD;IACD,OAAO,EAAE,OAAO,EAAE,CAAC;IACnB,KAAK,EAAE,OAAO,EAAE,CAAC;IACjB,QAAQ,EAAE,OAAO,EAAE,CAAC;CACrB,CA4BA;AAuBD,KAAK,SAAS,GAAG,CACf,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC1B,OAAO,CAAC,OAAO,CAAC,CAAC;AAsBtB;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,MAAM,GACb,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAchC;AAID,wBAAsB,WAAW,CAC/B,OAAO,EAAE,SAAS,EAClB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,MAAM,CAAC,CA8QjB;AAID,wBAAsB,cAAc,CAAC,OAAO,EAAE,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,CA4PxE;AAuBD,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,CAuL3E"}