@chrischall/mcp-utils 0.10.5 → 0.11.0

package/dist/http/net-atoms.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Small HTTP/network atoms shared across the fleet: `Retry-After` parsing
+ * (getyourguide / musicbrainz / viator / tripadvisor), host splitting
+ * (workday's multi-datacenter subdomains), descriptive User-Agent lines
+ * (musicbrainz / getyourguide — rate-limited public APIs block generic UAs),
+ * and RFC 6266 `Content-Disposition` filename extraction (ofw downloads).
+ */
+/** Options for {@link parseRetryAfterMs}. */
+export interface ParseRetryAfterOptions {
+    /** Delay when the header is missing or unparseable. Defaults to 2000 ms. */
+    defaultMs?: number;
+    /** Upper bound on the honored delay. Defaults to 30 000 ms. */
+    capMs?: number;
+}
+/**
+ * Parse an RFC 9110 `Retry-After` header (the delta-seconds form) into a
+ * bounded delay in milliseconds. Missing / non-numeric / negative values fall
+ * back to `defaultMs` **verbatim** — `capMs` bounds only header-derived delays
+ * (an upstream asking for a 10-minute wait shouldn't pin a tool call open, but
+ * the caller's own configured fallback is trusted as-is). The HTTP-date form
+ * is not parsed (no donor upstream uses it) and falls back to the default.
+ */
+export declare function parseRetryAfterMs(header: string | null | undefined, opts?: ParseRetryAfterOptions): number;
+/** Result of {@link splitHost}. */
+export interface SplitHost {
+    /** The registrable-ish domain: the last two labels (or the whole host when ≤ 2 labels). */
+    domain: string;
+    /** Everything left of the domain, when present (`'wd5'`, `'a.b'`). */
+    subdomain?: string;
+}
+/**
+ * Split a hostname into `{ domain, subdomain? }` where `domain` is the last
+ * two labels: `wd5.myworkday.com` → `{ domain: 'myworkday.com', subdomain:
+ * 'wd5' }`. Hosts with ≤ 2 labels return just `{ domain }`. Consolidates
+ * workday's `splitHost`, which computes a fetchproxy transport's
+ * `domains`/`defaultSubdomain` pair from the configured host. (Naive
+ * two-label split — public-suffix domains like `.co.uk` aren't special-cased;
+ * no fleet upstream lives on one.)
+ */
+export declare function splitHost(host: string): SplitHost;
+/**
+ * Build the descriptive `User-Agent` a rate-limited public API expects:
+ * `name/version (+contactUrl)`. MusicBrainz-style APIs block empty/generic
+ * UAs, so every fleet client should send one of these.
+ */
+export declare function buildUserAgent(name: string, version: string, contactUrl?: string): string;
+/**
+ * Extract the filename from a `Content-Disposition` header, preferring the
+ * RFC 6266 `filename*=UTF-8''percent-encoded` form over the quoted
+ * `filename="…"` fallback (matching ofw's download path). Returns `undefined`
+ * when the header is missing or carries no filename.
+ */
+export declare function parseContentDispositionFilename(header: string | null | undefined): string | undefined;
+//# sourceMappingURL=net-atoms.d.ts.map

package/dist/http/net-atoms.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"net-atoms.d.ts","sourceRoot":"","sources":["../../src/http/net-atoms.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,6CAA6C;AAC7C,MAAM,WAAW,sBAAsB;IACrC,4EAA4E;IAC5E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,+DAA+D;IAC/D,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACjC,IAAI,GAAE,sBAA2B,GAChC,MAAM,CAOR;AAED,mCAAmC;AACnC,MAAM,WAAW,SAAS;IACxB,2FAA2F;IAC3F,MAAM,EAAE,MAAM,CAAC;IACf,sEAAsE;IACtE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAOjD;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,CAEzF;AAED;;;;;GAKG;AACH,wBAAgB,+BAA+B,CAC7C,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAChC,MAAM,GAAG,SAAS,CAcpB"}

package/dist/http/net-atoms.js

@@ -0,0 +1,76 @@
+/**
+ * Small HTTP/network atoms shared across the fleet: `Retry-After` parsing
+ * (getyourguide / musicbrainz / viator / tripadvisor), host splitting
+ * (workday's multi-datacenter subdomains), descriptive User-Agent lines
+ * (musicbrainz / getyourguide — rate-limited public APIs block generic UAs),
+ * and RFC 6266 `Content-Disposition` filename extraction (ofw downloads).
+ */
+/**
+ * Parse an RFC 9110 `Retry-After` header (the delta-seconds form) into a
+ * bounded delay in milliseconds. Missing / non-numeric / negative values fall
+ * back to `defaultMs` **verbatim** — `capMs` bounds only header-derived delays
+ * (an upstream asking for a 10-minute wait shouldn't pin a tool call open, but
+ * the caller's own configured fallback is trusted as-is). The HTTP-date form
+ * is not parsed (no donor upstream uses it) and falls back to the default.
+ */
+export function parseRetryAfterMs(header, opts = {}) {
+    const defaultMs = opts.defaultMs ?? 2000;
+    const capMs = opts.capMs ?? 30_000;
+    if (header == null)
+        return defaultMs;
+    const trimmed = header.trim();
+    if (!/^\d+$/.test(trimmed))
+        return defaultMs;
+    return Math.min(Number(trimmed) * 1000, capMs);
+}
+/**
+ * Split a hostname into `{ domain, subdomain? }` where `domain` is the last
+ * two labels: `wd5.myworkday.com` → `{ domain: 'myworkday.com', subdomain:
+ * 'wd5' }`. Hosts with ≤ 2 labels return just `{ domain }`. Consolidates
+ * workday's `splitHost`, which computes a fetchproxy transport's
+ * `domains`/`defaultSubdomain` pair from the configured host. (Naive
+ * two-label split — public-suffix domains like `.co.uk` aren't special-cased;
+ * no fleet upstream lives on one.)
+ */
+export function splitHost(host) {
+    const labels = host.split('.');
+    if (labels.length <= 2)
+        return { domain: host };
+    return {
+        domain: labels.slice(-2).join('.'),
+        subdomain: labels.slice(0, -2).join('.'),
+    };
+}
+/**
+ * Build the descriptive `User-Agent` a rate-limited public API expects:
+ * `name/version (+contactUrl)`. MusicBrainz-style APIs block empty/generic
+ * UAs, so every fleet client should send one of these.
+ */
+export function buildUserAgent(name, version, contactUrl) {
+    return contactUrl ? `${name}/${version} (+${contactUrl})` : `${name}/${version}`;
+}
+/**
+ * Extract the filename from a `Content-Disposition` header, preferring the
+ * RFC 6266 `filename*=UTF-8''percent-encoded` form over the quoted
+ * `filename="…"` fallback (matching ofw's download path). Returns `undefined`
+ * when the header is missing or carries no filename.
+ */
+export function parseContentDispositionFilename(header) {
+    if (!header)
+        return undefined;
+    const star = /filename\*\s*=\s*(?:UTF-8|utf-8)''([^;]+)/.exec(header);
+    if (star?.[1]) {
+        try {
+            return decodeURIComponent(star[1].trim());
+        }
+        catch {
+            // Malformed percent-encoding — fall through to the quoted form.
+        }
+    }
+    const quoted = /filename\s*=\s*"([^"]+)"/.exec(header);
+    if (quoted?.[1])
+        return quoted[1];
+    const bare = /filename\s*=\s*([^;\s]+)/.exec(header);
+    return bare?.[1];
+}
+//# sourceMappingURL=net-atoms.js.map

package/dist/http/net-atoms.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"net-atoms.js","sourceRoot":"","sources":["../../src/http/net-atoms.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAUH;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB,CAC/B,MAAiC,EACjC,OAA+B,EAAE;IAEjC,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,IAAI,CAAC;IACzC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,MAAM,CAAC;IACnC,IAAI,MAAM,IAAI,IAAI;QAAE,OAAO,SAAS,CAAC;IACrC,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC;IAC9B,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC;QAAE,OAAO,SAAS,CAAC;IAC7C,OAAO,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,GAAG,IAAI,EAAE,KAAK,CAAC,CAAC;AACjD,CAAC;AAUD;;;;;;;;GAQG;AACH,MAAM,UAAU,SAAS,CAAC,IAAY;IACpC,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC/B,IAAI,MAAM,CAAC,MAAM,IAAI,CAAC;QAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;IAChD,OAAO;QACL,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC;QAClC,SAAS,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC;KACzC,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,IAAY,EAAE,OAAe,EAAE,UAAmB;IAC/E,OAAO,UAAU,CAAC,CAAC,CAAC,GAAG,IAAI,IAAI,OAAO,MAAM,UAAU,GAAG,CAAC,CAAC,CAAC,GAAG,IAAI,IAAI,OAAO,EAAE,CAAC;AACnF,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,+BAA+B,CAC7C,MAAiC;IAEjC,IAAI,CAAC,MAAM;QAAE,OAAO,SAAS,CAAC;IAC9B,MAAM,IAAI,GAAG,2CAA2C,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACtE,IAAI,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACd,IAAI,CAAC;YACH,OAAO,kBAAkB,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;QAC5C,CAAC;QAAC,MAAM,CAAC;YACP,gEAAgE;QAClE,CAAC;IACH,CAAC;IACD,MAAM,MAAM,GAAG,0BAA0B,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACvD,IAAI,MAAM,EAAE,CAAC,CAAC,CAAC;QAAE,OAAO,MAAM,CAAC,CAAC,CAAC,CAAC;IAClC,MAAM,IAAI,GAAG,0BAA0B,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACrD,OAAO,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;AACnB,CAAC"}

package/dist/http/response-cache.d.ts

@@ -0,0 +1,55 @@
+/**
+ * `createResponseCache` — bounded, tiered-TTL, in-memory response cache for
+ * billed / rate-limited APIs.
+ *
+ * Hoists the cache triplicated across flightaware / viator / tripadvisor:
+ * per-key `Map` of `{ expiresAt, value }`, a short `dynamic` tier for live data
+ * and a long `static` tier for reference data (airports, canonical lookups),
+ * a hard entry bound with expired-first-then-oldest eviction, and an
+ * injectable clock for deterministic tests. Pair the TTLs with
+ * `readTtlMsEnv('<SVC>_CACHE_TTL', …)` / `readTtlMsEnv('<SVC>_STATIC_CACHE_TTL', …)`.
+ *
+ * Writes must never be cached — only route reads through this.
+ */
+/** Default maximum number of live entries (the donor fleets' shared bound). */
+export declare const RESPONSE_CACHE_MAX_ENTRIES = 256;
+/** Options for {@link createResponseCache}. */
+export interface ResponseCacheOptions {
+    /**
+     * TTL per tier, in milliseconds. `dynamic` is the default tier; add any
+     * named tiers you need (the fleet convention is `static` for reference
+     * data). A tier with TTL `0` never stores — caching disabled.
+     */
+    ttlMs: {
+        dynamic: number;
+    } & Record<string, number>;
+    /** Max live entries before eviction. Defaults to {@link RESPONSE_CACHE_MAX_ENTRIES}. */
+    maxEntries?: number;
+    /** Injectable clock (defaults to `Date.now`) — for tests. */
+    now?: () => number;
+}
+/** The cache returned by {@link createResponseCache}. */
+export interface ResponseCache<V = unknown> {
+    /**
+     * The cached value for `key`, or `undefined` on miss/expiry. Tiers matter at
+     * WRITE time only — the TTL is baked into the entry by {@link set} /
+     * {@link fetchThrough} — so lookups take no tier.
+     */
+    get(key: string): V | undefined;
+    /** Store `value` for `key` under `tier`'s TTL (no-op when that TTL is 0). */
+    set(key: string, value: V, tier?: string): void;
+    /** Cache-through read: return the cached value or run `load` and cache it. */
+    fetchThrough(key: string, load: () => Promise<V>, tier?: string): Promise<V>;
+    /** Drop everything. */
+    clear(): void;
+    /** Number of entries currently held (including not-yet-swept expired ones). */
+    readonly size: number;
+}
+/**
+ * Build a bounded in-memory TTL cache with named tiers. Keys are caller-chosen
+ * — the donors key on the full request path (and body, for POST-read APIs like
+ * viator). Eviction on insert when full: expired entries first, then the
+ * oldest by insertion order.
+ */
+export declare function createResponseCache<V = unknown>(opts: ResponseCacheOptions): ResponseCache<V>;
+//# sourceMappingURL=response-cache.d.ts.map

package/dist/http/response-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"response-cache.d.ts","sourceRoot":"","sources":["../../src/http/response-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,+EAA+E;AAC/E,eAAO,MAAM,0BAA0B,MAAM,CAAC;AAE9C,+CAA+C;AAC/C,MAAM,WAAW,oBAAoB;IACnC;;;;OAIG;IACH,KAAK,EAAE;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpD,wFAAwF;IACxF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,6DAA6D;IAC7D,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED,yDAAyD;AACzD,MAAM,WAAW,aAAa,CAAC,CAAC,GAAG,OAAO;IACxC;;;;OAIG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS,CAAC;IAChC,6EAA6E;IAC7E,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAChD,8EAA8E;IAC9E,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAC7E,uBAAuB;IACvB,KAAK,IAAI,IAAI,CAAC;IACd,+EAA+E;IAC/E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,oBAAoB,GAAG,aAAa,CAAC,CAAC,CAAC,CA0D7F"}

package/dist/http/response-cache.js

@@ -0,0 +1,84 @@
+/**
+ * `createResponseCache` — bounded, tiered-TTL, in-memory response cache for
+ * billed / rate-limited APIs.
+ *
+ * Hoists the cache triplicated across flightaware / viator / tripadvisor:
+ * per-key `Map` of `{ expiresAt, value }`, a short `dynamic` tier for live data
+ * and a long `static` tier for reference data (airports, canonical lookups),
+ * a hard entry bound with expired-first-then-oldest eviction, and an
+ * injectable clock for deterministic tests. Pair the TTLs with
+ * `readTtlMsEnv('<SVC>_CACHE_TTL', …)` / `readTtlMsEnv('<SVC>_STATIC_CACHE_TTL', …)`.
+ *
+ * Writes must never be cached — only route reads through this.
+ */
+/** Default maximum number of live entries (the donor fleets' shared bound). */
+export const RESPONSE_CACHE_MAX_ENTRIES = 256;
+/**
+ * Build a bounded in-memory TTL cache with named tiers. Keys are caller-chosen
+ * — the donors key on the full request path (and body, for POST-read APIs like
+ * viator). Eviction on insert when full: expired entries first, then the
+ * oldest by insertion order.
+ */
+export function createResponseCache(opts) {
+    const now = opts.now ?? Date.now;
+    const maxEntries = opts.maxEntries ?? RESPONSE_CACHE_MAX_ENTRIES;
+    const store = new Map();
+    const ttlFor = (tier) => opts.ttlMs[tier] ?? 0;
+    function evictForInsert() {
+        if (store.size < maxEntries)
+            return;
+        // Pass 1: drop everything already expired.
+        const t = now();
+        for (const [key, entry] of store) {
+            if (entry.expiresAt <= t)
+                store.delete(key);
+        }
+        // Pass 2: still full → drop oldest insertions until under the bound.
+        while (store.size >= maxEntries) {
+            const oldest = store.keys().next();
+            if (oldest.done)
+                break;
+            store.delete(oldest.value);
+        }
+    }
+    function get(key) {
+        const entry = store.get(key);
+        if (!entry)
+            return undefined;
+        if (entry.expiresAt <= now()) {
+            store.delete(key);
+            return undefined;
+        }
+        return entry.value;
+    }
+    function set(key, value, tier = 'dynamic') {
+        const ttl = ttlFor(tier);
+        if (ttl <= 0)
+            return; // tier disabled
+        // Re-setting an existing key must not trigger eviction of a peer.
+        if (!store.has(key))
+            evictForInsert();
+        else
+            store.delete(key); // refresh insertion order
+        store.set(key, { expiresAt: now() + ttl, value });
+    }
+    return {
+        get,
+        set,
+        async fetchThrough(key, load, tier = 'dynamic') {
+            const hit = get(key);
+            if (hit !== undefined)
+                return hit;
+            const value = await load();
+            set(key, value, tier);
+            return value;
+        },
+        clear() {
+            store.clear();
+        },
+        get size() {
+            return store.size;
+        },
+    };
+}
+//# sourceMappingURL=response-cache.js.map

package/dist/http/response-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"response-cache.js","sourceRoot":"","sources":["../../src/http/response-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,+EAA+E;AAC/E,MAAM,CAAC,MAAM,0BAA0B,GAAG,GAAG,CAAC;AAkC9C;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAAc,IAA0B;IACzE,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC;IACjC,MAAM,UAAU,GAAG,IAAI,CAAC,UAAU,IAAI,0BAA0B,CAAC;IACjE,MAAM,KAAK,GAAG,IAAI,GAAG,EAA2C,CAAC;IAEjE,MAAM,MAAM,GAAG,CAAC,IAAY,EAAU,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAE/D,SAAS,cAAc;QACrB,IAAI,KAAK,CAAC,IAAI,GAAG,UAAU;YAAE,OAAO;QACpC,2CAA2C;QAC3C,MAAM,CAAC,GAAG,GAAG,EAAE,CAAC;QAChB,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,KAAK,EAAE,CAAC;YACjC,IAAI,KAAK,CAAC,SAAS,IAAI,CAAC;gBAAE,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAC9C,CAAC;QACD,qEAAqE;QACrE,OAAO,KAAK,CAAC,IAAI,IAAI,UAAU,EAAE,CAAC;YAChC,MAAM,MAAM,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC;YACnC,IAAI,MAAM,CAAC,IAAI;gBAAE,MAAM;YACvB,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAC7B,CAAC;IACH,CAAC;IAED,SAAS,GAAG,CAAC,GAAW;QACtB,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC7B,IAAI,CAAC,KAAK;YAAE,OAAO,SAAS,CAAC;QAC7B,IAAI,KAAK,CAAC,SAAS,IAAI,GAAG,EAAE,EAAE,CAAC;YAC7B,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YAClB,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,OAAO,KAAK,CAAC,KAAK,CAAC;IACrB,CAAC;IAED,SAAS,GAAG,CAAC,GAAW,EAAE,KAAQ,EAAE,IAAI,GAAG,SAAS;QAClD,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;QACzB,IAAI,GAAG,IAAI,CAAC;YAAE,OAAO,CAAC,gBAAgB;QACtC,kEAAkE;QAClE,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC;YAAE,cAAc,EAAE,CAAC;;YACjC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,0BAA0B;QAClD,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,GAAG,EAAE,GAAG,GAAG,EAAE,KAAK,EAAE,CAAC,CAAC;IACpD,CAAC;IAED,OAAO;QACL,GAAG;QACH,GAAG;QACH,KAAK,CAAC,YAAY,CAAC,GAAW,EAAE,IAAsB,EAAE,IAAI,GAAG,SAAS;YACtE,MAAM,GAAG,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC;YACrB,IAAI,GAAG,KAAK,SAAS;gBAAE,OAAO,GAAG,CAAC;YAClC,MAAM,KAAK,GAAG,MAAM,IAAI,EAAE,CAAC;YAC3B,GAAG,CAAC,GAAG,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC;YACtB,OAAO,KAAK,CAAC;QACf,CAAC;QACD,KAAK;YACH,KAAK,CAAC,KAAK,EAAE,CAAC;QAChB,CAAC;QACD,IAAI,IAAI;YACN,OAAO,KAAK,CAAC,IAAI,CAAC;QACpB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/index.d.ts

@@ -23,4 +23,5 @@ export * from './concurrency/index.js';
 export * from './dates/index.js';
 export * from './zod/index.js';
 export * from './auth/index.js';
+export * from './scrape/index.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +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,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,wBAAwB,CAAC;AACvC,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC"}
+{"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,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,wBAAwB,CAAC;AACvC,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC"}

package/dist/index.js

@@ -23,4 +23,5 @@ export * from './concurrency/index.js';
 export * from './dates/index.js';
 export * from './zod/index.js';
 export * from './auth/index.js';
+export * from './scrape/index.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +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,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,wBAAwB,CAAC;AACvC,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC"}
+{"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,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,wBAAwB,CAAC;AACvC,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC"}

package/dist/response/index.d.ts

@@ -31,4 +31,21 @@ export declare function flattenJsonApi(payload: unknown): unknown;
  * `deepMapStringField(data, 'eventDate', dmyToIso)`.
  */
 export declare function deepMapStringField<T>(value: T, field: string, map: (v: string) => string): T;
+/**
+ * Shallow-copy an object, dropping every `undefined`-valued key. `null` and
+ * falsy values survive — only `undefined` means "not provided".
+ *
+ * Consolidates the byte-identical `compact()` (skylight) / `prune()` (viator /
+ * alltrails) helpers the compact-projection tools call dozens of times per repo.
+ */
+export declare function pruneUndefined<T extends Record<string, unknown>>(obj: T): Partial<T>;
+/**
+ * Coerce a maybe-array to an array: an array passes through (same reference), a
+ * bare value is wrapped, and `null`/`undefined` become `[]`.
+ *
+ * Consolidates the `toArray` twins in canvas-parent / infinitecampus — both
+ * guard XML→JSON serializers where a single item arrives as a bare object
+ * rather than a 1-element array.
+ */
+export declare function toArray<T>(value: T | T[] | null | undefined): T[];
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/response/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAIzE;;;;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;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,CAK3D;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAoBxD;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,GAAG,CAAC,CAY5F"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/response/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAIzE;;;;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;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,CAK3D;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAoBxD;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,GAAG,CAAC,CAY5F;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAMpF;AAED;;;;;;;GAOG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,EAAE,GAAG,IAAI,GAAG,SAAS,GAAG,CAAC,EAAE,CAGjE"}

package/dist/response/index.js

@@ -87,4 +87,32 @@ export function deepMapStringField(value, field, map) {
     }
     return value;
 }
+/**
+ * Shallow-copy an object, dropping every `undefined`-valued key. `null` and
+ * falsy values survive — only `undefined` means "not provided".
+ *
+ * Consolidates the byte-identical `compact()` (skylight) / `prune()` (viator /
+ * alltrails) helpers the compact-projection tools call dozens of times per repo.
+ */
+export function pruneUndefined(obj) {
+    const out = {};
+    for (const key of Object.keys(obj)) {
+        if (obj[key] !== undefined)
+            out[key] = obj[key];
+    }
+    return out;
+}
+/**
+ * Coerce a maybe-array to an array: an array passes through (same reference), a
+ * bare value is wrapped, and `null`/`undefined` become `[]`.
+ *
+ * Consolidates the `toArray` twins in canvas-parent / infinitecampus — both
+ * guard XML→JSON serializers where a single item arrives as a bare object
+ * rather than a 1-element array.
+ */
+export function toArray(value) {
+    if (value === null || value === undefined)
+        return [];
+    return Array.isArray(value) ? value : [value];
+}
 //# sourceMappingURL=index.js.map

package/dist/response/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/response/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/response/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEnD;;;;GAIG;AACH,MAAM,UAAU,UAAU,CAAC,IAAa;IACtC,OAAO;QACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC;KACjE,CAAC;AACJ,CAAC;AAED,sEAAsE;AACtE,MAAM,CAAC,MAAM,UAAU,GAAG,UAAU,CAAC;AAErC,qEAAqE;AACrE,MAAM,UAAU,aAAa,CAAC,IAAY;IACxC,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;AAC/C,CAAC;AAED,yDAAyD;AACzD,MAAM,UAAU,WAAW,CAAC,MAAc,EAAE,QAAgB;IAC1D,OAAO;QACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC;KACrD,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,OAAe;IACzC,OAAO;QACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,aAAa,CAAC,OAAO,CAAC,EAAE,CAAC;QACzD,OAAO,EAAE,IAAI;KACd,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,OAAgB;IAC7C,MAAM,UAAU,GAAG,CAAC,IAAa,EAAW,EAAE;QAC5C,IAAI,IAAI,KAAK,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAC;QAC3D,MAAM,GAAG,GAAG,IAA+B,CAAC;QAC5C,MAAM,KAAK,GAAG,GAAG,CAAC,UAAU,CAAC;QAC7B,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YAChD,MAAM,MAAM,GAA4B,EAAE,GAAI,KAAiC,EAAE,CAAC;YAClF,IAAI,IAAI,IAAI,GAAG;gBAAE,MAAM,CAAC,EAAE,GAAG,GAAG,CAAC,EAAE,CAAC;YACpC,IAAI,MAAM,IAAI,GAAG;gBAAE,MAAM,CAAC,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC;YAC1C,OAAO,MAAM,CAAC;QAChB,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC,CAAC;IAEF,IAAI,OAAO,KAAK,IAAI,IAAI,OAAO,OAAO,KAAK,QAAQ;QAAE,OAAO,OAAO,CAAC;IACpE,MAAM,IAAI,GAAG,OAAkC,CAAC;IAChD,IAAI,CAAC,CAAC,MAAM,IAAI,IAAI,CAAC;QAAE,OAAO,OAAO,CAAC;IACtC,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;IACvB,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;IACrD,OAAO,UAAU,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAAI,KAAQ,EAAE,KAAa,EAAE,GAA0B;IACvF,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,KAAK,MAAM,IAAI,IAAI,KAAK;YAAE,kBAAkB,CAAC,IAAI,EAAE,KAAK,EAAE,GAAG,CAAC,CAAC;IACjE,CAAC;SAAM,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QACvD,MAAM,GAAG,GAAG,KAAgC,CAAC;QAC7C,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;YACnC,MAAM,CAAC,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC;YACnB,IAAI,GAAG,KAAK,KAAK,IAAI,OAAO,CAAC,KAAK,QAAQ;gBAAE,GAAG,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC;;gBACzD,kBAAkB,CAAC,CAAC,EAAE,KAAK,EAAE,GAAG,CAAC,CAAC;QACzC,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAoC,GAAM;IACtE,MAAM,GAAG,GAAe,EAAE,CAAC;IAC3B,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,GAAG,CAAmB,EAAE,CAAC;QACrD,IAAI,GAAG,CAAC,GAAG,CAAC,KAAK,SAAS;YAAE,GAAG,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC;IAClD,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,OAAO,CAAI,KAAiC;IAC1D,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,EAAE,CAAC;IACrD,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;AAChD,CAAC"}

package/dist/scrape/index.d.ts

@@ -0,0 +1,144 @@
+/**
+ * `scrape` — zero-dependency string/JSON extraction primitives for
+ * server-rendered pages.
+ *
+ * Consolidates the SSR JSON-store extraction stack the fleet re-implemented at
+ * least five times: musescore's `store.ts` (entity recovery + string-aware
+ * bracket matching), tock's `redux-state.ts` (top-level slice extraction +
+ * JS-literal repair) and `parse.ts` (cycle-guarded deep walkers), zillow's
+ * `page-props.ts` (`findArrayByShape`), etix's `parse.ts` (JSON-LD / OpenGraph
+ * / dataLayer readers), plus the entity-decode/strip-tags helpers duplicated in
+ * alltrails / musescore / signupgenius and the anti-XSSI guard strippers in
+ * workday / canvas / redfin.
+ *
+ * Everything here is pure string/JSON work — NO `node-html-parser`. DOM-level
+ * scraping (tables, link lists) lives in `@chrischall/mcp-utils/html`, which
+ * carries that optional peer dep; this module is safe for the core barrel.
+ */
+/**
+ * Decode HTML character references: decimal (`A`) and hex (`A`)
+ * numerics plus the common named entities. `&` is decoded **last** so a
+ * double-escaped entity survives exactly one level (`<` → `<`, not
+ * `<`) — the ordering both alltrails' `stripHtml` and musescore's `decodeText`
+ * depend on when recovering attribute-escaped JSON. Unknown entities pass
+ * through untouched.
+ */
+export declare function decodeHtmlEntities(text: string): string;
+/**
+ * Strip an HTML **fragment** to readable text: tags → spaces, entities decoded
+ * (via {@link decodeHtmlEntities}), whitespace collapsed and trimmed.
+ *
+ * For a full document where inline `<script>`/`<style>` *content* must not leak
+ * into the output, use `extractPlainTextFromHtml` from
+ * `@chrischall/mcp-utils/html` — this fragment-level helper does not remove
+ * element content, only markup.
+ */
+export declare function stripHtml(html: string): string;
+/**
+ * Replace bare JS `undefined` literals with `null` so a scraped JS object
+ * literal becomes parseable JSON. String-aware: occurrences inside single- or
+ * double-quoted strings are left alone, as are identifiers that merely contain
+ * the word. Consolidates tock's `sanitizeJsLiterals`.
+ */
+export declare function sanitizeJsLiterals(text: string): string;
+/**
+ * Given `text[start]` on a `{` or `[`, walk the balanced structure — tracking
+ * double- AND single-quoted strings and backslash escapes so brackets inside
+ * string literals don't terminate it early — and return the **exclusive** end
+ * index. Returns `-1` when `start` isn't on an opener or the structure never
+ * closes. Consolidates musescore's `matchBracket` and the brace-walk inside
+ * tock's `extractReduxSlice` (regex can't do this: the stores nest and escape).
+ */
+export declare function matchBalanced(text: string, start: number): number;
+/** Options for {@link extractJsonAfterMarker}. */
+export interface ExtractJsonOptions {
+    /** Run {@link sanitizeJsLiterals} before parsing (JS object literals). */
+    sanitize?: boolean;
+}
+/**
+ * Find the first of `markers` in `text`, skip to the next `{` or `[`, walk the
+ * balanced structure ({@link matchBalanced}), and `JSON.parse` it. Returns
+ * `null` on any failure — marker absent, no opener, unbalanced, or invalid
+ * JSON — so callers can branch without a try/catch.
+ *
+ * The array-capable, multi-marker, JS-literal-tolerant generalization of the
+ * `/html` subpath's `extractJsonFromHtml` (which is object-only and marker-form
+ * fixed). Use this for `window.$REDUX_STATE` slices (tock), `__NEXT_DATA__`
+ * analogues, and attribute-escaped stores (run the text through
+ * {@link decodeHtmlEntities} first when the blob is entity-escaped).
+ */
+export declare function extractJsonAfterMarker(text: string, markers: string | string[], opts?: ExtractJsonOptions): unknown;
+/**
+ * Parse every `<script type="application/ld+json">` block in the page,
+ * skipping malformed ones. Returns the parsed values in document order.
+ * Consolidates etix's / tripadvisor's ld+json block iteration.
+ *
+ * Linear-time by construction: `indexOf`-driven tag scanning (find `<script`,
+ * find its `>`, find `</script>`), never a `[^>]*>` regex — the previous
+ * single mega-regex was O(n³) and its `[^>]*>`-per-opener replacement is still
+ * O(n²); string `indexOf` doesn't backtrack, so an unterminated
+ * `<script type="application/ld+json"` flood can't pin the event loop.
+ */
+export declare function extractJsonLdBlocks(html: string): unknown[];
+/**
+ * Find the first schema.org entity of `@type === type` across the page's
+ * JSON-LD blocks — checking each block itself, its array items, its `@graph`
+ * items, and each candidate's `mainEntity` (the etix pattern: the Event often
+ * hides inside a `WebPage.mainEntity`). Returns the matching node, or `null`.
+ */
+export declare function findJsonLdEntity(html: string, type: string): Record<string, unknown> | null;
+/**
+ * Read a `<meta property="og:…" content="…">` value, tolerant of either
+ * attribute order (both occur in the wild — etix's `ogContent`) and of
+ * `name=`-keyed OpenGraph. The content is entity-decoded. Returns `undefined`
+ * when the property is absent.
+ *
+ * Linear-time by construction: `indexOf`-driven `<meta …>` scanning, reading
+ * the `property`/`content` attributes WITHIN each single (bounded) tag — never
+ * a `<meta\s[^>]*PROP[^>]*content…` regex, which backtracked quadratically on a
+ * flood of unterminated `<meta property=…` (a ReDoS on hostile scraped HTML).
+ */
+export declare function ogContent(html: string, property: string): string | undefined;
+/**
+ * Locate an array inside a drifting JSON container (a `pageProps` /
+ * `__NEXT_DATA__` blob): try `directKeys` first, then scan the container's
+ * top-level array values and return the first whose FIRST element passes
+ * `looksRight`. An empty array at a direct key is trusted (there is no first
+ * element to test). Returns `[]` on a miss — never `undefined` — so projections
+ * degrade to "no rows" instead of crashing when the upstream renames a key.
+ * Consolidates zillow's `page-props.ts#findArrayByShape`.
+ */
+export declare function findArrayByShape<T = unknown>(container: Record<string, unknown>, directKeys: string[], looksRight: (first: unknown) => boolean): T[];
+/**
+ * Depth-first, cycle-guarded walk collecting every array whose FIRST element
+ * passes `pred`. Recurses into matched arrays too (nested hits are collected).
+ * Consolidates tock's `collectArrays` — the "walk for the shape, don't
+ * hard-code the path" discipline for SSR stores.
+ */
+export declare function deepCollectArrays(root: unknown, pred: (first: unknown) => boolean): unknown[][];
+/**
+ * Depth-first, cycle-guarded search for the first non-array object passing
+ * `pred`. Returns `null` when nothing matches. Consolidates tock's
+ * `findObject`.
+ */
+export declare function deepFindObject(root: unknown, pred: (obj: Record<string, unknown>) => boolean): Record<string, unknown> | null;
+/**
+ * Detect a Cloudflare challenge interstitial by its DEFINITIVE markers only:
+ * the `_cf_chl_opt` bootstrap object or a `<title>Just a moment` page title.
+ * Deliberately does NOT match `cdn-cgi/challenge-platform` or
+ * `challenges.cloudflare.com` references — Cloudflare inlines those on CLEARED
+ * pages too, and matching them false-positives on legit pages (the musescore
+ * "search works but detail pages fail" bug). Consolidates the byte-identical
+ * predicates in musescore and tock.
+ */
+export declare function isCloudflareChallenge(html: string): boolean;
+/**
+ * Strip anti-XSSI / anti-JSON-hijacking guard prefixes from a response body so
+ * it parses as JSON: `)]}'`, `while(1);`, `for(;;);`, and `{}&&` (redfin's
+ * stingray envelope), plus surrounding whitespace, applied repeatedly until no
+ * guard remains. Unguarded input passes through unchanged. Consolidates
+ * workday's `stripJsonGuard`, canvas-parent's `while(1);` strip, and redfin's
+ * `stripStingrayPrefix`.
+ */
+export declare function stripJsonGuard(text: string): string;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/scrape/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAeH;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAQvD;AAiBD;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAK9C;AAQD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CA+BvD;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAyBjE;AAED,kDAAkD;AAClD,MAAM,WAAW,kBAAkB;IACjC,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,EAC1B,IAAI,GAAE,kBAAuB,GAC5B,OAAO,CA4BT;AA4BD;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,EAAE,CAsB3D;AASD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAe3F;AAOD;;;;;;;;;;GAUG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAgB5E;AAMD;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,GAAG,OAAO,EAC1C,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAClC,UAAU,EAAE,MAAM,EAAE,EACpB,UAAU,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,GACtC,CAAC,EAAE,CASL;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,GAAG,OAAO,EAAE,EAAE,CAgB/F;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,OAAO,EACb,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,GAC9C,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAsBhC;AAMD;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE3D;AAOD;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CASnD"}