@defai.digital/research-domain 13.4.0

package/LICENSE

@@ -0,0 +1,38 @@
+Business Source License 1.1
+
+Parameters
+
+Licensor: DEFAI Private Limited
+Licensed Work: AutomatosX
+The Licensed Work is (c) 2024-2025 DEFAI Private Limited
+Additional Use Grant: You may make production use of the Licensed Work,
+provided that your organization has less than US$2,000,000 in annual gross
+revenue in the prior fiscal year. "Production use" means use in a live
+production environment to support business or operational activities for end
+users.
+Change Date: Four years after the release date of the Licensed Work version
+Change License: Apache License, Version 2.0
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting other uses of the
+Licensed Work. The rights granted to you under this license are subject to the
+following condition.
+
+If you make any use of the Licensed Work, you must ensure that the Licensed
+Work, or any modified version of it, carries prominent notices stating that
+you have modified the Licensed Work.
+
+This license does not grant permission to use the Licensor's trademarks.
+
+The Licensed Work is provided "as is", without warranty of any kind, express
+or implied, including but not limited to the warranties of merchantability,
+fitness for a particular purpose and noninfringement. In no event shall the
+Licensor be liable for any claim, damages or other liability, whether in an
+action of contract, tort or otherwise, arising from, out of or in connection
+with the Licensed Work or the use or other dealings in the Licensed Work.
+
+On the Change Date, the Licensed Work will be made available under the Change
+License.

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Research Domain
+ *
+ * Deep research agent with live documentation fetching and knowledge synthesis.
+ */
+export type { WebFetcherPort, SynthesizerPort, ResearchCachePort, ResearchAgentOptions, ResearchAgent, } from './types.js';
+export { createStubWebFetcher, createWebFetcher } from './web-fetcher.js';
+export { createStubSynthesizer, detectConflicts, validateUrls } from './synthesizer.js';
+export { createResearchAgent } from './research-agent.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;;;;GAIG;AAGH,YAAY,EACV,cAAc,EACd,eAAe,EACf,iBAAiB,EACjB,oBAAoB,EACpB,aAAa,GACd,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAG1E,OAAO,EAAE,qBAAqB,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAGxF,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/index.js

@@ -0,0 +1,12 @@
+/**
+ * Research Domain
+ *
+ * Deep research agent with live documentation fetching and knowledge synthesis.
+ */
+// Web Fetcher
+export { createStubWebFetcher, createWebFetcher } from './web-fetcher.js';
+// Synthesizer
+export { createStubSynthesizer, detectConflicts, validateUrls } from './synthesizer.js';
+// Research Agent
+export { createResearchAgent } from './research-agent.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;;;;GAIG;AAWH,cAAc;AACd,OAAO,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAE1E,cAAc;AACd,OAAO,EAAE,qBAAqB,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAExF,iBAAiB;AACjB,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/research-agent.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Research Agent
+ *
+ * Main research agent implementation.
+ *
+ * Invariants:
+ * - INV-RSH-001: All sources cited in synthesis
+ * - INV-RSH-002: Confidence reflects source reliability
+ * - INV-RSH-003: Stale data flagged with warning
+ */
+import type { ResearchAgent, ResearchAgentOptions } from './types.js';
+/**
+ * Create a research agent
+ */
+export declare function createResearchAgent(options?: Partial<ResearchAgentOptions>): ResearchAgent;
+//# sourceMappingURL=research-agent.d.ts.map

package/dist/research-agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"research-agent.d.ts","sourceRoot":"","sources":["../src/research-agent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAcH,OAAO,KAAK,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAItE;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,GAAE,OAAO,CAAC,oBAAoB,CAAM,GAC1C,aAAa,CA+Ff"}

package/dist/research-agent.js

@@ -0,0 +1,154 @@
+/**
+ * Research Agent
+ *
+ * Main research agent implementation.
+ *
+ * Invariants:
+ * - INV-RSH-001: All sources cited in synthesis
+ * - INV-RSH-002: Confidence reflects source reliability
+ * - INV-RSH-003: Stale data flagged with warning
+ */
+import { calculateConfidence, hasStaleDataWarning, } from '@defai.digital/contracts';
+import { createStubWebFetcher } from './web-fetcher.js';
+import { createStubSynthesizer, detectConflicts } from './synthesizer.js';
+/**
+ * Create a research agent
+ */
+export function createResearchAgent(options = {}) {
+    const { webFetcher = createStubWebFetcher(), synthesizer = createStubSynthesizer(), cache, defaultTimeout = 60000, } = options;
+    return {
+        async research(request) {
+            const startTime = Date.now();
+            const resultId = crypto.randomUUID();
+            // Check cache
+            if (cache) {
+                const queryHash = hashQuery(request.query);
+                const cached = await cache.get(queryHash);
+                if (cached) {
+                    return cached;
+                }
+            }
+            // Fetch sources
+            const sources = await fetchSources(request, webFetcher, defaultTimeout);
+            // Calculate warnings
+            const warnings = [];
+            // INV-RSH-003: Check for stale data
+            if (sources.length > 0) {
+                const tempResult = {
+                    resultId,
+                    query: request.query,
+                    sources,
+                    synthesis: '',
+                    codeExamples: [],
+                    confidence: 0,
+                    warnings: [],
+                    durationMs: 0,
+                    completedAt: new Date().toISOString(),
+                };
+                if (hasStaleDataWarning(tempResult)) {
+                    warnings.push('Some sources may contain outdated information (>24 hours old)');
+                }
+            }
+            // Detect conflicts
+            // INV-RSH-202: Note conflicting information
+            const conflicts = detectConflicts(sources);
+            warnings.push(...conflicts);
+            // Synthesize results
+            let synthesis = '';
+            if (request.synthesize && sources.length > 0) {
+                synthesis = await synthesizer.synthesize({
+                    query: request.query,
+                    sources,
+                    style: 'detailed',
+                    includeCode: request.includeCode,
+                    maxLength: 10000,
+                });
+            }
+            // INV-RSH-002: Calculate confidence based on source reliability
+            const confidence = calculateConfidence(sources);
+            const result = {
+                resultId,
+                query: request.query,
+                sources,
+                synthesis,
+                codeExamples: extractCodeExamples(sources),
+                confidence,
+                warnings,
+                durationMs: Date.now() - startTime,
+                completedAt: new Date().toISOString(),
+            };
+            // Cache result
+            if (cache) {
+                const queryHash = hashQuery(request.query);
+                await cache.set(queryHash, result, 3600000); // 1 hour TTL
+            }
+            return result;
+        },
+        async fetch(request) {
+            return webFetcher.fetch(request);
+        },
+        async synthesize(request) {
+            return synthesizer.synthesize(request);
+        },
+    };
+}
+/**
+ * Fetch sources for a research query
+ * INV-RSH-102: Failed sources don't block
+ */
+async function fetchSources(request, webFetcher, timeout) {
+    const sources = [];
+    // INV-RSH-100: Enforce timeout
+    const timeoutPromise = new Promise((_, reject) => setTimeout(() => reject(new Error('Research timeout')), request.timeout ?? timeout));
+    try {
+        // Search for sources
+        const searchResults = await Promise.race([
+            webFetcher.search(request.query, request.maxSources),
+            timeoutPromise,
+        ]);
+        sources.push(...searchResults);
+    }
+    catch (error) {
+        // Log but don't fail
+        console.warn('[research-agent] Search failed:', error);
+    }
+    return sources;
+}
+/**
+ * Extract code examples from sources
+ */
+function extractCodeExamples(sources) {
+    const examples = [];
+    for (const source of sources) {
+        if (source.content) {
+            const codeBlockRegex = /```(\w+)?\n([\s\S]*?)```/g;
+            let match;
+            while ((match = codeBlockRegex.exec(source.content)) !== null) {
+                const code = match[2]?.trim();
+                if (code && code.length > 10) {
+                    examples.push({
+                        code,
+                        language: match[1] ?? 'text',
+                        source: source.url,
+                        tested: false,
+                    });
+                }
+            }
+        }
+    }
+    return examples.slice(0, 10); // Limit to 10 examples
+}
+/**
+ * Hash a query for caching
+ */
+function hashQuery(query) {
+    const normalized = query.toLowerCase().trim();
+    let hash = 0;
+    for (let i = 0; i < normalized.length; i++) {
+        const char = normalized.charCodeAt(i);
+        hash = (hash << 5) - hash + char;
+        hash = hash & hash;
+    }
+    return Math.abs(hash).toString(36);
+}
+//# sourceMappingURL=research-agent.js.map

package/dist/research-agent.js.map

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

package/dist/synthesizer.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Synthesizer
+ *
+ * Combine multiple research sources into a coherent answer.
+ *
+ * Invariants:
+ * - INV-RSH-200: Source attribution included
+ * - INV-RSH-201: Code examples attributed
+ * - INV-RSH-202: Conflicting information noted
+ * - INV-RSH-203: No hallucinated URLs
+ */
+import type { ResearchSource } from '@defai.digital/contracts';
+import type { SynthesizerPort } from './types.js';
+/**
+ * Create a stub synthesizer
+ */
+export declare function createStubSynthesizer(): SynthesizerPort;
+/**
+ * Detect conflicting information between sources
+ * INV-RSH-202: Conflicting information noted
+ */
+export declare function detectConflicts(sources: ResearchSource[]): string[];
+/**
+ * Validate all URLs in synthesis come from sources
+ * INV-RSH-203: No hallucinated URLs
+ */
+export declare function validateUrls(synthesis: string, sources: ResearchSource[]): boolean;
+//# sourceMappingURL=synthesizer.d.ts.map

package/dist/synthesizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"synthesizer.d.ts","sourceRoot":"","sources":["../src/synthesizer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAEV,cAAc,EAEf,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD;;GAEG;AACH,wBAAgB,qBAAqB,IAAI,eAAe,CAYvD;AAwGD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,cAAc,EAAE,GAAG,MAAM,EAAE,CA2BnE;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,EAAE,GAAG,OAAO,CAwBlF"}

package/dist/synthesizer.js

@@ -0,0 +1,159 @@
+/**
+ * Synthesizer
+ *
+ * Combine multiple research sources into a coherent answer.
+ *
+ * Invariants:
+ * - INV-RSH-200: Source attribution included
+ * - INV-RSH-201: Code examples attributed
+ * - INV-RSH-202: Conflicting information noted
+ * - INV-RSH-203: No hallucinated URLs
+ */
+/**
+ * Create a stub synthesizer
+ */
+export function createStubSynthesizer() {
+    return {
+        async synthesize(request) {
+            console.warn('[research-domain] Using stub synthesizer - no AI synthesis. ' +
+                'Inject a real SynthesizerPort for production use.');
+            // Create a simple concatenation-based synthesis
+            return createSimpleSynthesis(request);
+        },
+    };
+}
+/**
+ * Create a simple template-based synthesis
+ * Used as fallback when no AI synthesizer is available
+ */
+function createSimpleSynthesis(request) {
+    const { query, sources, includeCode } = request;
+    const lines = [];
+    lines.push(`# Research: ${query}\n`);
+    // Summary section
+    lines.push('## Summary\n');
+    lines.push(`Based on ${sources.length} source(s):\n`);
+    // Source summaries
+    for (const source of sources) {
+        const reliability = formatReliability(source.reliability);
+        lines.push(`### ${source.title} ${reliability}`);
+        lines.push(`*Source: ${source.url}*\n`);
+        lines.push(truncateText(source.snippet, 500));
+        lines.push('');
+    }
+    // Code examples
+    if (includeCode) {
+        const allCode = collectCodeExamples(sources);
+        if (allCode.length > 0) {
+            lines.push('\n## Code Examples\n');
+            for (const example of allCode.slice(0, 5)) {
+                lines.push(`\`\`\`${example.language}`);
+                lines.push(example.code);
+                lines.push('```');
+                if (example.source) {
+                    lines.push(`*Source: ${example.source}*`);
+                }
+                lines.push('');
+            }
+        }
+    }
+    // References
+    lines.push('\n## References\n');
+    for (let i = 0; i < sources.length; i++) {
+        lines.push(`${i + 1}. [${sources[i].title}](${sources[i].url})`);
+    }
+    return lines.join('\n');
+}
+/**
+ * Format reliability badge
+ */
+function formatReliability(reliability) {
+    switch (reliability) {
+        case 'official':
+            return '[Official]';
+        case 'community':
+            return '[Community]';
+        case 'generated':
+            return '[AI Generated]';
+        default:
+            return '';
+    }
+}
+/**
+ * Truncate text to max length
+ */
+function truncateText(text, maxLength) {
+    if (text.length <= maxLength) {
+        return text;
+    }
+    return text.slice(0, maxLength - 3) + '...';
+}
+/**
+ * Collect code examples from all sources
+ * INV-RSH-201: Code examples attributed
+ */
+function collectCodeExamples(sources) {
+    const examples = [];
+    for (const source of sources) {
+        if (source.content) {
+            // Extract code blocks from content
+            const codeBlockRegex = /```(\w+)?\n([\s\S]*?)```/g;
+            let match;
+            while ((match = codeBlockRegex.exec(source.content)) !== null) {
+                examples.push({
+                    code: match[2]?.trim() ?? '',
+                    language: match[1] ?? 'text',
+                    source: source.url,
+                    tested: false,
+                });
+            }
+        }
+    }
+    return examples;
+}
+/**
+ * Detect conflicting information between sources
+ * INV-RSH-202: Conflicting information noted
+ */
+export function detectConflicts(sources) {
+    const conflicts = [];
+    // Simple heuristic: check for contradictory keywords
+    const contradictoryPairs = [
+        ['deprecated', 'recommended'],
+        ['avoid', 'best practice'],
+        ['not recommended', 'should use'],
+        ['legacy', 'modern'],
+    ];
+    for (const [word1, word2] of contradictoryPairs) {
+        const hasWord1 = sources.some((s) => s.snippet.toLowerCase().includes(word1));
+        const hasWord2 = sources.some((s) => s.snippet.toLowerCase().includes(word2));
+        if (hasWord1 && hasWord2) {
+            conflicts.push(`Sources have conflicting views: some mention "${word1}" while others suggest "${word2}"`);
+        }
+    }
+    return conflicts;
+}
+/**
+ * Validate all URLs in synthesis come from sources
+ * INV-RSH-203: No hallucinated URLs
+ */
+export function validateUrls(synthesis, sources) {
+    const urlRegex = /https?:\/\/[^\s\)]+/g;
+    const urls = synthesis.match(urlRegex) ?? [];
+    const sourceUrls = new Set(sources.map((s) => s.url));
+    for (const url of urls) {
+        // Allow URLs that are from our sources
+        if (sourceUrls.has(url)) {
+            continue;
+        }
+        // Allow URLs that are subpaths of source URLs
+        const isSubpath = Array.from(sourceUrls).some((sourceUrl) => url.startsWith(sourceUrl.replace(/\/$/, '')));
+        if (isSubpath) {
+            continue;
+        }
+        // URL not from sources - this is a hallucination
+        return false;
+    }
+    return true;
+}
+//# sourceMappingURL=synthesizer.js.map

package/dist/synthesizer.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Research Domain Types
+ *
+ * Port interfaces for the research agent.
+ */
+import type { ResearchRequest, ResearchResult, ResearchSource, FetchRequest, FetchResponse, SynthesisRequest } from '@defai.digital/contracts';
+/**
+ * Port for fetching web content
+ */
+export interface WebFetcherPort {
+    /**
+     * Fetch content from a URL
+     */
+    fetch(request: FetchRequest): Promise<FetchResponse>;
+    /**
+     * Search the web for a query
+     */
+    search(query: string, maxResults: number): Promise<ResearchSource[]>;
+}
+/**
+ * Port for synthesizing research results
+ */
+export interface SynthesizerPort {
+    /**
+     * Synthesize sources into a coherent answer
+     */
+    synthesize(request: SynthesisRequest): Promise<string>;
+}
+/**
+ * Port for caching research results
+ */
+export interface ResearchCachePort {
+    /**
+     * Get cached result for query
+     */
+    get(queryHash: string): Promise<ResearchResult | null>;
+    /**
+     * Cache a result
+     */
+    set(queryHash: string, result: ResearchResult, ttlMs: number): Promise<void>;
+    /**
+     * Invalidate cache entry
+     */
+    invalidate(queryHash: string): Promise<void>;
+}
+/**
+ * Research agent options
+ */
+export interface ResearchAgentOptions {
+    /**
+     * Web fetcher port
+     */
+    webFetcher: WebFetcherPort;
+    /**
+     * Synthesizer port
+     */
+    synthesizer: SynthesizerPort;
+    /**
+     * Optional cache port
+     */
+    cache?: ResearchCachePort;
+    /**
+     * Default timeout for operations
+     */
+    defaultTimeout?: number;
+    /**
+     * Maximum concurrent fetches
+     * INV-RSH-101: Limited to 5
+     */
+    maxConcurrentFetches?: number;
+}
+/**
+ * Research agent interface
+ */
+export interface ResearchAgent {
+    /**
+     * Execute a research query
+     */
+    research(request: ResearchRequest): Promise<ResearchResult>;
+    /**
+     * Fetch a single URL
+     */
+    fetch(request: FetchRequest): Promise<FetchResponse>;
+    /**
+     * Synthesize existing sources
+     */
+    synthesize(request: SynthesisRequest): Promise<string>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EACV,eAAe,EACf,cAAc,EACd,cAAc,EACd,YAAY,EACZ,aAAa,EACb,gBAAgB,EACjB,MAAM,0BAA0B,CAAC;AAElC;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B;;OAEG;IACH,KAAK,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IAErD;;OAEG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC;CACtE;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B;;OAEG;IACH,UAAU,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACxD;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;OAEG;IACH,GAAG,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;IAEvD;;OAEG;IACH,GAAG,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,cAAc,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE7E;;OAEG;IACH,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9C;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC;;OAEG;IACH,UAAU,EAAE,cAAc,CAAC;IAE3B;;OAEG;IACH,WAAW,EAAE,eAAe,CAAC;IAE7B;;OAEG;IACH,KAAK,CAAC,EAAE,iBAAiB,CAAC;IAE1B;;OAEG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB;;;OAGG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IAE5D;;OAEG;IACH,KAAK,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IAErD;;OAEG;IACH,UAAU,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACxD"}

package/dist/types.js

@@ -0,0 +1,7 @@
+/**
+ * Research Domain Types
+ *
+ * Port interfaces for the research agent.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/dist/web-fetcher.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Web Fetcher
+ *
+ * Fetch and parse web content for research.
+ *
+ * Invariants:
+ * - INV-RSH-100: Timeout enforced
+ * - INV-RSH-101: Concurrent fetches limited
+ * - INV-RSH-102: Failed sources don't block
+ */
+import type { WebFetcherPort } from './types.js';
+/**
+ * Create a stub web fetcher
+ */
+export declare function createStubWebFetcher(): WebFetcherPort;
+/**
+ * Create a web fetcher with rate limiting
+ */
+export declare function createWebFetcher(options: {
+    maxConcurrent?: number;
+    defaultTimeout?: number;
+    userAgent?: string;
+}): WebFetcherPort;
+//# sourceMappingURL=web-fetcher.d.ts.map

package/dist/web-fetcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"web-fetcher.d.ts","sourceRoot":"","sources":["../src/web-fetcher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AASH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAsCjD;;GAEG;AACH,wBAAgB,oBAAoB,IAAI,cAAc,CA4BrD;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE;IACxC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,GAAG,cAAc,CAkFjB"}