@j0hanz/superfetch 1.0.0

package/dist/services/fetcher.service.js

@@ -0,0 +1,122 @@
+import axios from 'axios';
+import { config } from '../config/index.js';
+import { FetchError, TimeoutError } from '../errors/app-error.js';
+// Headers that should not be overridden by custom headers (security)
+const BLOCKED_HEADERS = new Set([
+    'host',
+    'authorization',
+    'cookie',
+    'x-forwarded-for',
+    'x-real-ip',
+    'proxy-authorization',
+]);
+/**
+ * Sanitize custom headers to prevent injection of sensitive headers
+ */
+function sanitizeHeaders(headers) {
+    if (!headers || Object.keys(headers).length === 0) {
+        return undefined;
+    }
+    const sanitized = {};
+    for (const [key, value] of Object.entries(headers)) {
+        if (!BLOCKED_HEADERS.has(key.toLowerCase())) {
+            sanitized[key] = value;
+        }
+    }
+    return Object.keys(sanitized).length > 0 ? sanitized : undefined;
+}
+/**
+ * Calculates exponential backoff delay with jitter
+ */
+function calculateBackoff(attempt, maxDelay = 10000) {
+    const baseDelay = Math.min(1000 * Math.pow(2, attempt - 1), maxDelay);
+    // Add jitter (±25%)
+    const jitter = baseDelay * 0.25 * (Math.random() * 2 - 1);
+    return Math.round(baseDelay + jitter);
+}
+class FetcherService {
+    client;
+    constructor() {
+        this.client = axios.create({
+            timeout: config.fetcher.timeout,
+            maxRedirects: config.fetcher.maxRedirects,
+            maxContentLength: config.fetcher.maxContentLength,
+            headers: {
+                'User-Agent': config.fetcher.userAgent,
+                Accept: 'text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8',
+                'Accept-Language': 'en-US,en;q=0.5',
+                'Accept-Encoding': 'gzip, deflate, br',
+                Connection: 'keep-alive',
+            },
+            // Validate status - only 2xx responses are valid
+            validateStatus: (status) => status >= 200 && status < 300,
+        });
+    }
+    /**
+     * Fetches HTML content from a URL
+     * @throws {FetchError} on network or HTTP errors
+     * @throws {TimeoutError} on request timeout
+     */
+    async fetchUrl(url, customHeaders) {
+        const requestConfig = {
+            method: 'GET',
+            url,
+            responseType: 'text',
+        };
+        // Add sanitized custom headers if provided
+        const sanitized = sanitizeHeaders(customHeaders);
+        if (sanitized) {
+            requestConfig.headers = { ...requestConfig.headers, ...sanitized };
+        }
+        try {
+            const response = await this.client.request(requestConfig);
+            return response.data;
+        }
+        catch (error) {
+            if (!axios.isAxiosError(error)) {
+                throw new FetchError(`Unexpected error: ${error instanceof Error ? error.message : 'Unknown'}`, url);
+            }
+            const axiosError = error;
+            if (axiosError.code === 'ECONNABORTED' || axiosError.code === 'ETIMEDOUT') {
+                throw new TimeoutError(config.fetcher.timeout, true);
+            }
+            if (axiosError.response) {
+                throw new FetchError(`HTTP ${axiosError.response.status}: ${axiosError.response.statusText}`, url, axiosError.response.status);
+            }
+            if (axiosError.request) {
+                throw new FetchError(`Network error: Could not reach ${url}`, url);
+            }
+            throw new FetchError(axiosError.message, url);
+        }
+    }
+    /**
+     * Fetches URL with exponential backoff retry logic
+     * @throws {FetchError} after all retries exhausted
+     */
+    async fetchUrlWithRetry(url, customHeaders, maxRetries = 3) {
+        let lastError;
+        for (let attempt = 1; attempt <= maxRetries; attempt++) {
+            try {
+                return await this.fetchUrl(url, customHeaders);
+            }
+            catch (error) {
+                lastError = error instanceof Error ? error : new Error('Unknown error');
+                // Don't retry on client errors (4xx) except 429 (rate limited)
+                if (error instanceof FetchError && error.httpStatus) {
+                    const status = error.httpStatus;
+                    if (status >= 400 && status < 500 && status !== 429) {
+                        throw error;
+                    }
+                }
+                if (attempt < maxRetries) {
+                    const delay = calculateBackoff(attempt);
+                    await new Promise((resolve) => setTimeout(resolve, delay));
+                }
+            }
+        }
+        throw new FetchError(`Failed after ${maxRetries} attempts: ${lastError?.message ?? 'Unknown error'}`, url);
+    }
+}
+// Singleton instance
+export const fetcherService = new FetcherService();
+//# sourceMappingURL=fetcher.service.js.map

package/dist/services/fetcher.service.js.map

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

package/dist/services/logger.d.ts

@@ -0,0 +1,5 @@
+export declare function logInfo(message: string, meta?: Record<string, unknown>): void;
+export declare function logWarn(message: string, meta?: Record<string, unknown>): void;
+export declare function logDebug(message: string, meta?: Record<string, unknown>): void;
+export declare function logError(message: string, error?: Error | Record<string, unknown>): void;
+//# sourceMappingURL=logger.d.ts.map

package/dist/services/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/services/logger.ts"],"names":[],"mappings":"AAyCA,wBAAgB,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAE7E;AAED,wBAAgB,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAE7E;AAED,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAE9E;AAED,wBAAgB,QAAQ,CACtB,OAAO,EAAE,MAAM,EACf,KAAK,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACtC,IAAI,CAQN"}

package/dist/services/logger.js

@@ -0,0 +1,48 @@
+import winston from 'winston';
+import { config } from '../config/index.js';
+import path from 'path';
+const logsDir = path.join(process.cwd(), 'logs');
+const logger = winston.createLogger({
+    level: config.logging.level,
+    format: winston.format.combine(winston.format.timestamp({ format: 'YYYY-MM-DD HH:mm:ss' }), winston.format.errors({ stack: true }), winston.format.splat(), winston.format.json()),
+    defaultMeta: { service: 'superfetch' },
+    transports: [
+        new winston.transports.File({
+            filename: path.join(logsDir, 'combined.log'),
+            maxsize: 5242880,
+            maxFiles: 5,
+        }),
+        new winston.transports.File({
+            filename: path.join(logsDir, 'error.log'),
+            level: 'error',
+            maxsize: 5242880,
+            maxFiles: 5,
+        }),
+    ],
+});
+if (process.env.NODE_ENV !== 'production') {
+    logger.add(new winston.transports.Console({
+        format: winston.format.combine(winston.format.colorize(), winston.format.simple()),
+    }));
+}
+export function logInfo(message, meta) {
+    if (config.logging.enabled)
+        logger.info(message, meta);
+}
+export function logWarn(message, meta) {
+    if (config.logging.enabled)
+        logger.warn(message, meta);
+}
+export function logDebug(message, meta) {
+    if (config.logging.enabled)
+        logger.debug(message, meta);
+}
+export function logError(message, error) {
+    if (!config.logging.enabled)
+        return;
+    const errorMeta = error instanceof Error
+        ? { error: error.message, stack: error.stack }
+        : error;
+    logger.error(message, errorMeta);
+}
+//# sourceMappingURL=logger.js.map

package/dist/services/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/services/logger.ts"],"names":[],"mappings":"AAAA,OAAO,OAAO,MAAM,SAAS,CAAC;AAC9B,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAC5C,OAAO,IAAI,MAAM,MAAM,CAAC;AAExB,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,MAAM,CAAC,CAAC;AAEjD,MAAM,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAClC,KAAK,EAAE,MAAM,CAAC,OAAO,CAAC,KAAK;IAC3B,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,OAAO,CAC5B,OAAO,CAAC,MAAM,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,qBAAqB,EAAE,CAAC,EAC3D,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,EACtC,OAAO,CAAC,MAAM,CAAC,KAAK,EAAE,EACtB,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,CACtB;IACD,WAAW,EAAE,EAAE,OAAO,EAAE,YAAY,EAAE;IACtC,UAAU,EAAE;QACV,IAAI,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC;YAC1B,QAAQ,EAAE,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,cAAc,CAAC;YAC5C,OAAO,EAAE,OAAO;YAChB,QAAQ,EAAE,CAAC;SACZ,CAAC;QACF,IAAI,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC;YAC1B,QAAQ,EAAE,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,WAAW,CAAC;YACzC,KAAK,EAAE,OAAO;YACd,OAAO,EAAE,OAAO;YAChB,QAAQ,EAAE,CAAC;SACZ,CAAC;KACH;CACF,CAAC,CAAC;AAEH,IAAI,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,YAAY,EAAE,CAAC;IAC1C,MAAM,CAAC,GAAG,CACR,IAAI,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC;QAC7B,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,OAAO,CAC5B,OAAO,CAAC,MAAM,CAAC,QAAQ,EAAE,EACzB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,CACxB;KACF,CAAC,CACH,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,OAAO,CAAC,OAAe,EAAE,IAA8B;IACrE,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO;QAAE,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;AACzD,CAAC;AAED,MAAM,UAAU,OAAO,CAAC,OAAe,EAAE,IAA8B;IACrE,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO;QAAE,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;AACzD,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,OAAe,EAAE,IAA8B;IACtE,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO;QAAE,MAAM,CAAC,KAAK,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;AAC1D,CAAC;AAED,MAAM,UAAU,QAAQ,CACtB,OAAe,EACf,KAAuC;IAEvC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,OAAO;QAAE,OAAO;IAEpC,MAAM,SAAS,GACb,KAAK,YAAY,KAAK;QACpB,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE;QAC9C,CAAC,CAAC,KAAK,CAAC;IACZ,MAAM,CAAC,KAAK,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;AACnC,CAAC"}

package/dist/services/logger.service.d.ts

@@ -0,0 +1,5 @@
+export declare const logInfo: (message: string, meta?: Record<string, unknown>) => void;
+export declare const logWarn: (message: string, meta?: Record<string, unknown>) => void;
+export declare const logDebug: (message: string, meta?: Record<string, unknown>) => void;
+export declare const logError: (message: string, error?: Error | Record<string, unknown>) => void;
+//# sourceMappingURL=logger.service.d.ts.map

package/dist/services/logger.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.service.d.ts","sourceRoot":"","sources":["../../src/services/logger.service.ts"],"names":[],"mappings":"AA+CA,eAAO,MAAM,OAAO,GAAI,SAAS,MAAM,EAAE,OAAO,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,SAItE,CAAC;AAEF,eAAO,MAAM,OAAO,GAAI,SAAS,MAAM,EAAE,OAAO,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,SAItE,CAAC;AAEF,eAAO,MAAM,QAAQ,GAAI,SAAS,MAAM,EAAE,OAAO,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,SAIvE,CAAC;AAEF,eAAO,MAAM,QAAQ,GACnB,SAAS,MAAM,EACf,QAAQ,KAAK,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,SASxC,CAAC"}

package/dist/services/logger.service.js

@@ -0,0 +1,57 @@
+import winston from 'winston';
+import { config } from '../config/index.js';
+import path from 'path';
+// Create logs directory path
+const logsDir = path.join(process.cwd(), 'logs');
+// Create logger instance
+const logger = winston.createLogger({
+    level: config.logging.level,
+    format: winston.format.combine(winston.format.timestamp({ format: 'YYYY-MM-DD HH:mm:ss' }), winston.format.errors({ stack: true }), winston.format.splat(), winston.format.json()),
+    defaultMeta: { service: 'superfetch' },
+    transports: [
+        // Write all logs to combined.log
+        new winston.transports.File({
+            filename: path.join(logsDir, 'combined.log'),
+            maxsize: 5242880, // 5MB
+            maxFiles: 5,
+        }),
+        // Write error logs to error.log
+        new winston.transports.File({
+            filename: path.join(logsDir, 'error.log'),
+            level: 'error',
+            maxsize: 5242880, // 5MB
+            maxFiles: 5,
+        }),
+    ],
+});
+// Add console transport in development
+if (process.env.NODE_ENV !== 'production') {
+    logger.add(new winston.transports.Console({
+        format: winston.format.combine(winston.format.colorize(), winston.format.simple()),
+    }));
+}
+// Export convenience methods
+export const logInfo = (message, meta) => {
+    if (config.logging.enabled) {
+        logger.info(message, meta);
+    }
+};
+export const logWarn = (message, meta) => {
+    if (config.logging.enabled) {
+        logger.warn(message, meta);
+    }
+};
+export const logDebug = (message, meta) => {
+    if (config.logging.enabled) {
+        logger.debug(message, meta);
+    }
+};
+export const logError = (message, error) => {
+    if (config.logging.enabled) {
+        const errorMeta = error instanceof Error
+            ? { error: error.message, stack: error.stack }
+            : error;
+        logger.error(message, errorMeta);
+    }
+};
+//# sourceMappingURL=logger.service.js.map

package/dist/services/logger.service.js.map

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

package/dist/services/parser.d.ts

@@ -0,0 +1,6 @@
+import type { ContentBlockUnion } from '../types/index.js';
+/**
+ * Parses HTML content and extracts semantic blocks
+ */
+export declare function parseHtml(html: string): ContentBlockUnion[];
+//# sourceMappingURL=parser.d.ts.map

package/dist/services/parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../../src/services/parser.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAOV,iBAAiB,EAClB,MAAM,mBAAmB,CAAC;AAyJ3B;;GAEG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,EAAE,CAc3D"}

package/dist/services/parser.js

@@ -0,0 +1,152 @@
+import * as cheerio from 'cheerio';
+import { sanitizeText } from '../utils/sanitizer.js';
+import { config } from '../config/index.js';
+function parseHeading($, element) {
+    const text = sanitizeText($(element).text());
+    if (!text)
+        return null;
+    return {
+        type: 'heading',
+        level: parseInt(element.tagName.substring(1), 10),
+        text,
+    };
+}
+function parseParagraph($, element) {
+    const text = sanitizeText($(element).text());
+    if (!text || text.length < config.extraction.minParagraphLength)
+        return null;
+    return { type: 'paragraph', text };
+}
+function parseList($, element) {
+    const items = [];
+    $(element)
+        .find('li')
+        .each((_, li) => {
+        const text = sanitizeText($(li).text());
+        if (text)
+            items.push(text);
+    });
+    if (items.length === 0)
+        return null;
+    return {
+        type: 'list',
+        ordered: element.tagName.toLowerCase() === 'ol',
+        items,
+    };
+}
+function parseCode($, element) {
+    const text = $(element).text().trim();
+    if (!text)
+        return null;
+    const className = $(element).attr('class') || '';
+    const languageMatch = className.match(/language-(\w+)/);
+    return {
+        type: 'code',
+        language: languageMatch?.[1],
+        text,
+    };
+}
+function parseTable($, element) {
+    const headers = [];
+    const rows = [];
+    const $table = $(element);
+    // Extract headers from thead or first row
+    $table.find('thead th, thead td').each((_, cell) => {
+        headers.push(sanitizeText($(cell).text()));
+    });
+    if (headers.length === 0) {
+        $table
+            .find('tr')
+            .first()
+            .find('th, td')
+            .each((_, cell) => {
+            headers.push(sanitizeText($(cell).text()));
+        });
+    }
+    // Extract body rows
+    const rowsSelector = headers.length > 0 ? 'tbody tr, tr:not(:first)' : 'tbody tr, tr';
+    $table.find(rowsSelector).each((_, row) => {
+        const cells = [];
+        $(row)
+            .find('td, th')
+            .each((_, cell) => {
+            cells.push(sanitizeText($(cell).text()));
+        });
+        if (cells.length > 0)
+            rows.push(cells);
+    });
+    if (rows.length === 0)
+        return null;
+    return {
+        type: 'table',
+        headers: headers.length > 0 ? headers : undefined,
+        rows,
+    };
+}
+function parseImage($, element) {
+    const src = $(element).attr('src');
+    if (!src)
+        return null;
+    return {
+        type: 'image',
+        src,
+        alt: $(element).attr('alt') || undefined,
+    };
+}
+const ELEMENT_PARSERS = {
+    h1: parseHeading,
+    h2: parseHeading,
+    h3: parseHeading,
+    h4: parseHeading,
+    h5: parseHeading,
+    h6: parseHeading,
+    p: parseParagraph,
+    ul: parseList,
+    ol: parseList,
+    pre: parseCode,
+    code: parseCode,
+    table: parseTable,
+    img: parseImage,
+};
+function isParseableTag(tag) {
+    return tag in ELEMENT_PARSERS;
+}
+function parseElement($, node) {
+    if (!('tagName' in node) || typeof node.tagName !== 'string')
+        return null;
+    const tagName = node.tagName.toLowerCase();
+    if (!isParseableTag(tagName))
+        return null;
+    return ELEMENT_PARSERS[tagName]($, node);
+}
+function filterBlocks(blocks) {
+    return blocks.filter((block) => {
+        switch (block.type) {
+            case 'paragraph':
+            case 'heading':
+            case 'code':
+                return block.text.length > 0;
+            case 'list':
+                return block.items.length > 0;
+            default:
+                return true;
+        }
+    });
+}
+/**
+ * Parses HTML content and extracts semantic blocks
+ */
+export function parseHtml(html) {
+    const $ = cheerio.load(html);
+    const blocks = [];
+    $('script, style, noscript, iframe, svg').remove();
+    $('body')
+        .find('h1, h2, h3, h4, h5, h6, p, ul, ol, pre, code, table, img')
+        .each((_, element) => {
+        const block = parseElement($, element);
+        if (block)
+            blocks.push(block);
+    });
+    return filterBlocks(blocks);
+}
+//# sourceMappingURL=parser.js.map

package/dist/services/parser.js.map

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

package/dist/services/parser.service.d.ts

@@ -0,0 +1,42 @@
+import type { ContentBlockUnion } from '../types/index.js';
+declare class ParserService {
+    /**
+     * Parses HTML content and extracts semantic blocks
+     */
+    parseHtml(html: string): ContentBlockUnion[];
+    /**
+     * Parses a single element into a content block
+     */
+    private parseElement;
+    /**
+     * Parses a heading element
+     */
+    private parseHeading;
+    /**
+     * Parses a paragraph element
+     */
+    private parseParagraph;
+    /**
+     * Parses a list element
+     */
+    private parseList;
+    /**
+     * Parses a code element
+     */
+    private parseCode;
+    /**
+     * Parses a table element
+     */
+    private parseTable;
+    /**
+     * Parses an image element
+     */
+    private parseImage;
+    /**
+     * Filters out empty or invalid blocks
+     */
+    private filterBlocks;
+}
+export declare const parserService: ParserService;
+export {};
+//# sourceMappingURL=parser.service.d.ts.map

package/dist/services/parser.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parser.service.d.ts","sourceRoot":"","sources":["../../src/services/parser.service.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAOV,iBAAiB,EAClB,MAAM,mBAAmB,CAAC;AAE3B,cAAM,aAAa;IACjB;;OAEG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,EAAE;IAoB5C;;OAEG;IACH,OAAO,CAAC,YAAY;IAuCpB;;OAEG;IACH,OAAO,CAAC,YAAY;IAepB;;OAEG;IACH,OAAO,CAAC,cAAc;IAgBtB;;OAEG;IACH,OAAO,CAAC,SAAS;IAwBjB;;OAEG;IACH,OAAO,CAAC,SAAS;IAkBjB;;OAEG;IACH,OAAO,CAAC,UAAU;IA+ClB;;OAEG;IACH,OAAO,CAAC,UAAU;IAelB;;OAEG;IACH,OAAO,CAAC,YAAY;CAiBrB;AAGD,eAAO,MAAM,aAAa,eAAsB,CAAC"}