@chrischall/mcp-utils 0.1.0

package/dist/http/index.d.ts

@@ -0,0 +1,202 @@
+/**
+ * `http` — bearer-auth API-client kit.
+ *
+ * Consolidates the ~100-line `client.ts` boilerplate copy-pasted across ~8 MCP
+ * servers (splitwise/tempo/ioffice/app-store-connect/zola): a bearer-auth fetch
+ * wrapper with one-shot 429 retry, 401 mapping, 204 handling, and redacted error
+ * formatting — plus the small URL/JWT/cookie utilities scattered across the
+ * fleet (canvas Link-header parsing, IC/signupgenius cookie jars, zola JWT
+ * decode).
+ *
+ * Security posture (design §"Bearer-token / error-message leakage"):
+ *  - {@link formatApiError} runs every upstream body through the shared
+ *    {@link truncateErrorMessage} (redaction THEN truncation) so bearer tokens
+ *    and JWTs never reach a tool result, even when an upstream echoes the
+ *    request back.
+ *  - {@link createApiClient} never embeds the token in a thrown message; a 401
+ *    yields a fixed "unauthorized" string, not the credential.
+ */
+/** Retry policy for transient (HTTP 429) responses. */
+export interface RetryPolicy {
+    /** Number of retries after the initial attempt. The fleet default is 1. */
+    count: number;
+    /** Delay before each retry, in milliseconds. The fleet default is 2000. */
+    delayMs: number;
+}
+/** Options for {@link createApiClient}. */
+export interface ApiClientOptions {
+    /** Absolute base URL; request paths are appended verbatim. A trailing slash is trimmed. */
+    baseUrl: string;
+    /**
+     * Resolve the current bearer token. Called per request so the caller can
+     * refresh/rotate transparently. May be sync or async. Return `undefined`/`''`
+     * to send no `Authorization` header (e.g. cookie-authenticated APIs).
+     */
+    getToken: () => string | undefined | Promise<string | undefined>;
+    /**
+     * 429 retry policy. Defaults to `{ count: 1, delayMs: 2000 }` — the
+     * fleet-wide "retry once after 2s" behavior. Set `count: 0` to disable.
+     */
+    retry?: RetryPolicy;
+    /** Human name of the upstream service, used in error messages. Defaults to the host. */
+    serviceName?: string;
+    /** Injectable fetch (for tests). Defaults to the global `fetch`. */
+    fetchImpl?: typeof fetch;
+    /** Injectable sleep (for tests). Defaults to `setTimeout`. */
+    sleep?: (ms: number) => Promise<void>;
+}
+/** A request body and/or extra headers for a single call. */
+export interface RequestOptions {
+    /** JSON-serialized into the request body when present. */
+    body?: unknown;
+    /** Extra request headers, merged over the defaults. */
+    headers?: Record<string, string>;
+    /** Query params appended via {@link buildQueryString} when present. */
+    query?: Record<string, unknown>;
+}
+/** The minimal client surface returned by {@link createApiClient}. */
+export interface ApiClient {
+    /**
+     * Authenticated JSON request. Returns the parsed body, or `undefined` for a
+     * 204 / empty body. Throws on 401 (unauthorized), exhausted-429, and other
+     * non-2xx responses (with a redacted, truncated message).
+     */
+    fetchJson: <T = unknown>(method: string, path: string, opts?: RequestOptions) => Promise<T>;
+    /** Authenticated request returning the raw response body as text (e.g. HTML scrapes). */
+    fetchHtml: (method: string, path: string, opts?: RequestOptions) => Promise<string>;
+}
+/** Thrown for an upstream 401. Carries the status so callers can trigger a re-auth. */
+export declare class UnauthorizedError extends Error {
+    readonly status = 401;
+    constructor(service: string);
+}
+/** Thrown when a 429 persists after the retry budget is exhausted. */
+export declare class RateLimitedError extends Error {
+    readonly status = 429;
+    constructor(service: string);
+}
+/**
+ * Build a bearer-auth fetch client with one-shot 429 retry, 401 mapping, 204 /
+ * empty-body handling, and redacted error formatting.
+ *
+ * Consolidates the structurally-identical `client.ts#doRequest` across
+ * splitwise/tempo/ioffice/app-store-connect/zola. The retry/401/429 behavior is
+ * the hardened superset: 401 → {@link UnauthorizedError} (never echoing the
+ * token), 429 → sleep(`delayMs`) and replay up to `count` times then
+ * {@link RateLimitedError}, 204/empty → `undefined`, other non-2xx →
+ * {@link formatApiError}.
+ */
+export declare function createApiClient(opts: ApiClientOptions): ApiClient;
+/**
+ * Build a URL query string from a params object, returning `''` or
+ * `?k=v&k2=v2`. Skips `undefined`, `null`, and empty-string values; expands
+ * arrays into repeated keys (skipping null/undefined/empty array members); and
+ * percent-encodes keys and values.
+ *
+ * Consolidates the divergent `buildQueryString` / inline `URLSearchParams`
+ * variants across compass/redfin/zillow/homes/opentable/tempo/ioffice into one
+ * superset (array support + empty-string skipping + encoding).
+ */
+export declare function buildQueryString(params: Record<string, unknown>): string;
+/**
+ * Build a request body from `args`, including only the `optionalFields` that are
+ * actually present (not `undefined`). `null` is preserved — some APIs use it to
+ * clear a field — only `undefined` (i.e. "not provided") is dropped.
+ *
+ * Consolidates tempo's optional-field body builder: lets a tool forward a wide
+ * args object and emit a minimal PATCH/POST body.
+ */
+export declare function buildOptionalBody<T extends Record<string, unknown>, K extends keyof T>(args: T, optionalFields: readonly K[]): Partial<Pick<T, K>>;
+/** Options for {@link formatApiError}. */
+export interface FormatApiErrorOptions {
+    /** Service name woven into the prefix. Defaults to `'API'`. */
+    service?: string;
+    /** Truncation budget for the upstream body. Defaults to the shared 500. */
+    max?: number;
+}
+/**
+ * Format a non-2xx upstream response into a single, client-safe error string:
+ * `"{service} error {status} for {METHOD} {path}: {body}"`.
+ *
+ * SECURITY: the upstream `errorText` is run through the shared
+ * {@link truncateErrorMessage} (redaction of `Bearer <token>` / JWTs FIRST,
+ * then truncation) so a raw body that echoes the request — or an upstream that
+ * leaks a token — never reaches the caller. The method is upper-cased; an
+ * empty/whitespace body is dropped entirely rather than printing a dangling
+ * colon.
+ */
+export declare function formatApiError(status: number, method: string, path: string, errorText: string, opts?: FormatApiErrorOptions): string;
+/** The RFC 5988 rels callers care about for pagination. */
+export interface ParsedLinkHeader {
+    next?: string;
+    prev?: string;
+    first?: string;
+    last?: string;
+    /** Any other rels present, keyed by rel name. */
+    [rel: string]: string | undefined;
+}
+/**
+ * Parse an RFC 5988 `Link` header into a `{ rel: url }` map. Malformed entries
+ * are skipped; `rel="next"` and bare `rel=next` are both accepted. A missing or
+ * empty header yields `{}`.
+ *
+ * Consolidates canvas's pagination Link parser.
+ */
+export declare function parseLinkHeader(header: string | null | undefined): ParsedLinkHeader;
+/** A parsed Set-Cookie jar: deduplicated name→value plus a ready `Cookie` header. */
+export interface CookieJar {
+    /** Surviving cookies, name → value (last value wins, deletions removed). */
+    cookies: Record<string, string>;
+    /** Pre-joined `name=value; name2=value2` string for the `Cookie` request header. */
+    cookieHeader: string;
+}
+/**
+ * Parse `Set-Cookie` headers into a deduplicated {@link CookieJar}.
+ *
+ * Login responses commonly send deletion markers (`Max-Age=0` or an epoch
+ * `Expires`) alongside real cookies; forwarding both the delete and set form of
+ * a name makes some upstreams (e.g. IC) reject the request. This parser:
+ *  - drops deletion markers (`Max-Age=0`, epoch `Expires`),
+ *  - drops empty-value cookies (clearing instructions),
+ *  - deduplicates by name with **last value wins**, preserving order.
+ *
+ * Accepts the array from `Headers.getSetCookie()` (or a single joined string —
+ * which it splits defensively, though `getSetCookie()` is strongly preferred
+ * since commas inside `Expires` make string-splitting lossy).
+ *
+ * Consolidates the IC/signupgenius cookie-jar logic.
+ */
+export declare function parseCookieJar(setCookieHeaders: string[] | string | null | undefined): CookieJar;
+/**
+ * Decode a JWT's `exp` claim (seconds since epoch). Throws when the structure is
+ * invalid or `exp` is missing/non-numeric — the strict variant zola uses for the
+ * token it depends on. For a lenient probe, use {@link validateJwtExpiry}.
+ */
+export declare function decodeJwtExp(token: string): number;
+/**
+ * Best-effort extraction of a session id from a JWT payload, checking
+ * `session_id` then `sid`. Returns `null` for an undecodable token or absent
+ * claim (never throws) — the lenient variant zola uses for the WAF session
+ * header.
+ */
+export declare function decodeJwtSessionId(token: string): string | null;
+/** Result of {@link validateJwtExpiry}. */
+export interface JwtExpiryStatus {
+    /** True when the token is past its `exp` (or undecodable / lacks `exp`). */
+    expired: boolean;
+    /** Seconds until expiry (negative once expired); omitted when undecodable. */
+    expiresIn?: number;
+    /** Human-readable caution when the token is expired or near expiry. */
+    warning?: string;
+}
+/**
+ * Non-throwing expiry probe for a bearer JWT. Returns `{ expired, expiresIn?,
+ * warning? }`. An undecodable token (or one lacking a numeric `exp`) is treated
+ * as `expired: true` with a warning — failing closed so a malformed token forces
+ * a refresh rather than being sent and bouncing as a 401.
+ *
+ * Near-expiry (within {@link NEAR_EXPIRY_SKEW_SEC}) yields a warning while still
+ * reporting `expired: false`, so callers can refresh proactively.
+ */
+export declare function validateJwtExpiry(token: string, nowMs?: number): JwtExpiryStatus;
+//# sourceMappingURL=index.d.ts.map

package/dist/http/index.d.ts.map

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

package/dist/http/index.js

@@ -0,0 +1,341 @@
+/**
+ * `http` — bearer-auth API-client kit.
+ *
+ * Consolidates the ~100-line `client.ts` boilerplate copy-pasted across ~8 MCP
+ * servers (splitwise/tempo/ioffice/app-store-connect/zola): a bearer-auth fetch
+ * wrapper with one-shot 429 retry, 401 mapping, 204 handling, and redacted error
+ * formatting — plus the small URL/JWT/cookie utilities scattered across the
+ * fleet (canvas Link-header parsing, IC/signupgenius cookie jars, zola JWT
+ * decode).
+ *
+ * Security posture (design §"Bearer-token / error-message leakage"):
+ *  - {@link formatApiError} runs every upstream body through the shared
+ *    {@link truncateErrorMessage} (redaction THEN truncation) so bearer tokens
+ *    and JWTs never reach a tool result, even when an upstream echoes the
+ *    request back.
+ *  - {@link createApiClient} never embeds the token in a thrown message; a 401
+ *    yields a fixed "unauthorized" string, not the credential.
+ */
+import { truncateErrorMessage } from '../errors/index.js';
+const DEFAULT_RETRY = { count: 1, delayMs: 2000 };
+const defaultSleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** Thrown for an upstream 401. Carries the status so callers can trigger a re-auth. */
+export class UnauthorizedError extends Error {
+    status = 401;
+    constructor(service) {
+        super(`Unauthorized (401) from ${service} — the token is missing, invalid, or expired.`);
+        this.name = 'UnauthorizedError';
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+/** Thrown when a 429 persists after the retry budget is exhausted. */
+export class RateLimitedError extends Error {
+    status = 429;
+    constructor(service) {
+        super(`Rate limited (429) by ${service} after retries.`);
+        this.name = 'RateLimitedError';
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+function hostOf(baseUrl) {
+    try {
+        return new URL(baseUrl).host;
+    }
+    catch {
+        return baseUrl;
+    }
+}
+/**
+ * Build a bearer-auth fetch client with one-shot 429 retry, 401 mapping, 204 /
+ * empty-body handling, and redacted error formatting.
+ *
+ * Consolidates the structurally-identical `client.ts#doRequest` across
+ * splitwise/tempo/ioffice/app-store-connect/zola. The retry/401/429 behavior is
+ * the hardened superset: 401 → {@link UnauthorizedError} (never echoing the
+ * token), 429 → sleep(`delayMs`) and replay up to `count` times then
+ * {@link RateLimitedError}, 204/empty → `undefined`, other non-2xx →
+ * {@link formatApiError}.
+ */
+export function createApiClient(opts) {
+    const base = opts.baseUrl.replace(/\/+$/, '');
+    const retry = opts.retry ?? DEFAULT_RETRY;
+    const service = opts.serviceName ?? hostOf(opts.baseUrl);
+    const doFetch = opts.fetchImpl ?? fetch;
+    const sleep = opts.sleep ?? defaultSleep;
+    async function send(method, path, opt) {
+        const token = await opts.getToken();
+        const headers = {
+            Accept: 'application/json',
+            ...(opt.body !== undefined ? { 'Content-Type': 'application/json' } : {}),
+            ...(token ? { Authorization: `Bearer ${token}` } : {}),
+            ...opt.headers,
+        };
+        const query = opt.query ? buildQueryString(opt.query) : '';
+        const url = `${base}${path}${query}`;
+        let attempt = 0;
+        // attempt 0 is the initial request; up to `retry.count` further attempts on 429.
+        for (;;) {
+            const res = await doFetch(url, {
+                method,
+                headers,
+                ...(opt.body !== undefined ? { body: JSON.stringify(opt.body) } : {}),
+            });
+            if (res.status === 429 && attempt < retry.count) {
+                attempt += 1;
+                await sleep(retry.delayMs);
+                continue;
+            }
+            return res;
+        }
+    }
+    async function fetchJson(method, path, opt = {}) {
+        const res = await send(method, path, opt);
+        if (res.status === 401)
+            throw new UnauthorizedError(service);
+        if (res.status === 429)
+            throw new RateLimitedError(service);
+        if (res.status === 204)
+            return undefined;
+        const text = await res.text();
+        if (!res.ok) {
+            throw new Error(formatApiError(res.status, method, path, text, { service }));
+        }
+        if (text.length === 0)
+            return undefined;
+        return JSON.parse(text);
+    }
+    async function fetchHtml(method, path, opt = {}) {
+        const headers = { Accept: 'text/html,*/*', ...opt.headers };
+        const res = await send(method, path, { ...opt, headers });
+        if (res.status === 401)
+            throw new UnauthorizedError(service);
+        if (res.status === 429)
+            throw new RateLimitedError(service);
+        const text = await res.text();
+        if (!res.ok) {
+            throw new Error(formatApiError(res.status, method, path, text, { service }));
+        }
+        return text;
+    }
+    return { fetchJson, fetchHtml };
+}
+// ---------------------------------------------------------------------------
+// buildQueryString
+// ---------------------------------------------------------------------------
+/**
+ * Build a URL query string from a params object, returning `''` or
+ * `?k=v&k2=v2`. Skips `undefined`, `null`, and empty-string values; expands
+ * arrays into repeated keys (skipping null/undefined/empty array members); and
+ * percent-encodes keys and values.
+ *
+ * Consolidates the divergent `buildQueryString` / inline `URLSearchParams`
+ * variants across compass/redfin/zillow/homes/opentable/tempo/ioffice into one
+ * superset (array support + empty-string skipping + encoding).
+ */
+export function buildQueryString(params) {
+    const parts = [];
+    for (const [key, value] of Object.entries(params)) {
+        if (value === undefined || value === null || value === '')
+            continue;
+        if (Array.isArray(value)) {
+            for (const item of value) {
+                if (item === undefined || item === null || item === '')
+                    continue;
+                parts.push(`${encodeURIComponent(key)}=${encodeURIComponent(String(item))}`);
+            }
+        }
+        else {
+            parts.push(`${encodeURIComponent(key)}=${encodeURIComponent(String(value))}`);
+        }
+    }
+    return parts.length > 0 ? `?${parts.join('&')}` : '';
+}
+// ---------------------------------------------------------------------------
+// buildOptionalBody
+// ---------------------------------------------------------------------------
+/**
+ * Build a request body from `args`, including only the `optionalFields` that are
+ * actually present (not `undefined`). `null` is preserved — some APIs use it to
+ * clear a field — only `undefined` (i.e. "not provided") is dropped.
+ *
+ * Consolidates tempo's optional-field body builder: lets a tool forward a wide
+ * args object and emit a minimal PATCH/POST body.
+ */
+export function buildOptionalBody(args, optionalFields) {
+    const body = {};
+    for (const field of optionalFields) {
+        if (args[field] !== undefined) {
+            body[field] = args[field];
+        }
+    }
+    return body;
+}
+/**
+ * Format a non-2xx upstream response into a single, client-safe error string:
+ * `"{service} error {status} for {METHOD} {path}: {body}"`.
+ *
+ * SECURITY: the upstream `errorText` is run through the shared
+ * {@link truncateErrorMessage} (redaction of `Bearer <token>` / JWTs FIRST,
+ * then truncation) so a raw body that echoes the request — or an upstream that
+ * leaks a token — never reaches the caller. The method is upper-cased; an
+ * empty/whitespace body is dropped entirely rather than printing a dangling
+ * colon.
+ */
+export function formatApiError(status, method, path, errorText, opts = {}) {
+    const service = opts.service ?? 'API';
+    const head = `${service} error ${status} for ${method.toUpperCase()} ${path}`;
+    const safe = truncateErrorMessage(errorText ?? '', opts.max).trim();
+    return safe.length > 0 ? `${head}: ${safe}` : head;
+}
+/**
+ * Parse an RFC 5988 `Link` header into a `{ rel: url }` map. Malformed entries
+ * are skipped; `rel="next"` and bare `rel=next` are both accepted. A missing or
+ * empty header yields `{}`.
+ *
+ * Consolidates canvas's pagination Link parser.
+ */
+export function parseLinkHeader(header) {
+    const out = {};
+    if (!header)
+        return out;
+    for (const part of header.split(',')) {
+        const m = part.trim().match(/^<([^>]+)>\s*;\s*rel="?([^";]+)"?/);
+        if (m && m[1] && m[2])
+            out[m[2].trim()] = m[1];
+    }
+    return out;
+}
+const MAX_AGE_ZERO_RE = /(?:^|;)\s*Max-Age\s*=\s*0\s*(?:;|$)/i;
+const EXPIRES_EPOCH_RE = /(?:^|;)\s*Expires\s*=\s*Thu,\s*01\s*Jan\s*1970/i;
+/**
+ * Parse `Set-Cookie` headers into a deduplicated {@link CookieJar}.
+ *
+ * Login responses commonly send deletion markers (`Max-Age=0` or an epoch
+ * `Expires`) alongside real cookies; forwarding both the delete and set form of
+ * a name makes some upstreams (e.g. IC) reject the request. This parser:
+ *  - drops deletion markers (`Max-Age=0`, epoch `Expires`),
+ *  - drops empty-value cookies (clearing instructions),
+ *  - deduplicates by name with **last value wins**, preserving order.
+ *
+ * Accepts the array from `Headers.getSetCookie()` (or a single joined string —
+ * which it splits defensively, though `getSetCookie()` is strongly preferred
+ * since commas inside `Expires` make string-splitting lossy).
+ *
+ * Consolidates the IC/signupgenius cookie-jar logic.
+ */
+export function parseCookieJar(setCookieHeaders) {
+    const entries = setCookieHeaders == null
+        ? []
+        : Array.isArray(setCookieHeaders)
+            ? setCookieHeaders
+            : splitSetCookie(setCookieHeaders);
+    const jar = new Map();
+    for (const entry of entries) {
+        if (MAX_AGE_ZERO_RE.test(entry) || EXPIRES_EPOCH_RE.test(entry))
+            continue;
+        const nameValue = (entry.split(';')[0] ?? '').trim();
+        const eqIdx = nameValue.indexOf('=');
+        if (eqIdx < 1)
+            continue;
+        const name = nameValue.slice(0, eqIdx).trim();
+        const value = nameValue.slice(eqIdx + 1).trim();
+        if (!value)
+            continue;
+        jar.set(name, value);
+    }
+    const cookies = {};
+    for (const [k, v] of jar)
+        cookies[k] = v;
+    const cookieHeader = [...jar.entries()].map(([k, v]) => `${k}=${v}`).join('; ');
+    return { cookies, cookieHeader };
+}
+/** Best-effort split of a single joined `set-cookie` string (no `getSetCookie()`). */
+function splitSetCookie(header) {
+    // Split on commas that are NOT part of an Expires date ("Thu, 01 Jan ...").
+    return header
+        .split(/,(?=\s*[^;,\s]+\s*=)/)
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+}
+// ---------------------------------------------------------------------------
+// JWT helpers
+// ---------------------------------------------------------------------------
+/** Decode the base64url JWT payload to an object, or `null` if it can't be parsed. */
+function decodeJwtPayload(token) {
+    if (typeof token !== 'string')
+        return null;
+    const parts = token.split('.');
+    if (parts.length < 2 || !parts[1])
+        return null;
+    try {
+        const json = Buffer.from(parts[1], 'base64url').toString('utf8');
+        const payload = JSON.parse(json);
+        if (payload === null || typeof payload !== 'object')
+            return null;
+        return payload;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Decode a JWT's `exp` claim (seconds since epoch). Throws when the structure is
+ * invalid or `exp` is missing/non-numeric — the strict variant zola uses for the
+ * token it depends on. For a lenient probe, use {@link validateJwtExpiry}.
+ */
+export function decodeJwtExp(token) {
+    const payload = decodeJwtPayload(token);
+    if (!payload) {
+        throw new Error('Invalid JWT: could not decode payload (expected a 3-part base64url token)');
+    }
+    const exp = payload['exp'];
+    if (typeof exp !== 'number') {
+        throw new Error('Invalid JWT: missing numeric "exp" claim');
+    }
+    return exp;
+}
+/**
+ * Best-effort extraction of a session id from a JWT payload, checking
+ * `session_id` then `sid`. Returns `null` for an undecodable token or absent
+ * claim (never throws) — the lenient variant zola uses for the WAF session
+ * header.
+ */
+export function decodeJwtSessionId(token) {
+    const payload = decodeJwtPayload(token);
+    if (!payload)
+        return null;
+    const sid = payload['session_id'] ?? payload['sid'];
+    return typeof sid === 'string' ? sid : null;
+}
+/** Tokens within this many seconds of `exp` are flagged as near-expiry. */
+const NEAR_EXPIRY_SKEW_SEC = 300;
+/**
+ * Non-throwing expiry probe for a bearer JWT. Returns `{ expired, expiresIn?,
+ * warning? }`. An undecodable token (or one lacking a numeric `exp`) is treated
+ * as `expired: true` with a warning — failing closed so a malformed token forces
+ * a refresh rather than being sent and bouncing as a 401.
+ *
+ * Near-expiry (within {@link NEAR_EXPIRY_SKEW_SEC}) yields a warning while still
+ * reporting `expired: false`, so callers can refresh proactively.
+ */
+export function validateJwtExpiry(token, nowMs = Date.now()) {
+    const payload = decodeJwtPayload(token);
+    const exp = payload?.['exp'];
+    if (typeof exp !== 'number') {
+        return { expired: true, warning: 'Token could not be decoded or has no expiry; treat as expired.' };
+    }
+    const nowSec = Math.floor(nowMs / 1000);
+    const expiresIn = exp - nowSec;
+    if (expiresIn <= 0) {
+        return { expired: true, expiresIn, warning: 'Token has expired; refresh before use.' };
+    }
+    if (expiresIn <= NEAR_EXPIRY_SKEW_SEC) {
+        return {
+            expired: false,
+            expiresIn,
+            warning: `Token expires in ${expiresIn}s; refresh soon.`,
+        };
+    }
+    return { expired: false, expiresIn };
+}
+//# sourceMappingURL=index.js.map

package/dist/http/index.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * `@chrischall/mcp-utils` — core barrel.
+ *
+ * Re-exports the framework-agnostic building blocks every server in the fleet
+ * reaches for: server bootstrap, tool-result formatting, helpful errors,
+ * hardened env/config, a bearer API-client kit, zod atoms, and the auth
+ * resolver skeletons.
+ *
+ * Heavier / optional-dependency modules are published as subpath entries and
+ * are intentionally NOT re-exported here:
+ *   - `@chrischall/mcp-utils/session`     session registries + token manager
+ *   - `@chrischall/mcp-utils/fetchproxy`  fetchproxy transport adapter
+ *   - `@chrischall/mcp-utils/html`        opt-in HTML scraping helpers
+ *   - `@chrischall/mcp-utils/test`        in-memory test harness
+ */
+export * from './server/index.js';
+export * from './response/index.js';
+export * from './errors/index.js';
+export * from './config/index.js';
+export * from './http/index.js';
+export * from './zod/index.js';
+export * from './auth/index.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC"}

package/dist/index.js

@@ -0,0 +1,23 @@
+/**
+ * `@chrischall/mcp-utils` — core barrel.
+ *
+ * Re-exports the framework-agnostic building blocks every server in the fleet
+ * reaches for: server bootstrap, tool-result formatting, helpful errors,
+ * hardened env/config, a bearer API-client kit, zod atoms, and the auth
+ * resolver skeletons.
+ *
+ * Heavier / optional-dependency modules are published as subpath entries and
+ * are intentionally NOT re-exported here:
+ *   - `@chrischall/mcp-utils/session`     session registries + token manager
+ *   - `@chrischall/mcp-utils/fetchproxy`  fetchproxy transport adapter
+ *   - `@chrischall/mcp-utils/html`        opt-in HTML scraping helpers
+ *   - `@chrischall/mcp-utils/test`        in-memory test harness
+ */
+export * from './server/index.js';
+export * from './response/index.js';
+export * from './errors/index.js';
+export * from './config/index.js';
+export * from './http/index.js';
+export * from './zod/index.js';
+export * from './auth/index.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC"}

package/dist/response/index.d.ts

@@ -0,0 +1,22 @@
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+/**
+ * Wrap any JSON-serialisable value as an MCP tool result. This is the single
+ * most duplicated snippet across the fleet:
+ *   `{ content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] }`
+ */
+export declare function textResult(data: unknown): CallToolResult;
+/** Alias for {@link textResult} — pretty-printed JSON tool result. */
+export declare const jsonResult: typeof textResult;
+/** Return a raw string as a text tool result (no JSON stringify). */
+export declare function rawTextResult(text: string): CallToolResult;
+/** Return a base64 image as an MCP image tool result. */
+export declare function imageResult(base64: string, mimeType: string): CallToolResult;
+/** Return an error tool result (`isError: true`) carrying a message. */
+export declare function errorResult(message: string): CallToolResult;
+/**
+ * Collapse a JSON:API-shaped payload (`{ data: { id, type, attributes } }` or an
+ * array thereof) into plain objects with `id`/`type` merged into attributes.
+ * Used by skylight-mcp; opt-in (callers pass payloads they know are JSON:API).
+ */
+export declare function flattenJsonApi(payload: unknown): unknown;
+//# sourceMappingURL=index.d.ts.map

package/dist/response/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/response/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAEzE;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,OAAO,GAAG,cAAc,CAIxD;AAED,sEAAsE;AACtE,eAAO,MAAM,UAAU,mBAAa,CAAC;AAErC,qEAAqE;AACrE,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,CAE1D;AAED,yDAAyD;AACzD,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,cAAc,CAI5E;AAED,wEAAwE;AACxE,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,CAK3D;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAoBxD"}