@j0hanz/superfetch 1.0.5 → 1.1.0

package/dist/middleware/error-handler.js

@@ -1,26 +1,24 @@
-import { AppError, RateLimitError, ValidationError } from '../errors/index.js';
+import { FetchError } from '../errors/app-error.js';
 import { logError } from '../services/logger.js';
-export function errorHandler(err, _req, res, 
-// eslint-disable-next-line @typescript-eslint/no-unused-vars -- Required by Express error handler signature
-_next) {
-    const isAppError = err instanceof AppError;
-    const statusCode = isAppError ? err.statusCode : 500;
-    const code = isAppError ? err.code : 'INTERNAL_ERROR';
-    const message = isAppError && err.isOperational ? err.message : 'Internal Server Error';
-    logError(`HTTP ${statusCode}: ${err.message}`, err);
-    if (err instanceof RateLimitError) {
-        res.set('Retry-After', String(err.retryAfter));
+export function errorHandler(err, req, res) {
+    const isFetchError = err instanceof FetchError;
+    const statusCode = isFetchError ? err.statusCode : 500;
+    const code = isFetchError ? err.code : 'INTERNAL_ERROR';
+    const message = isFetchError ? err.message : 'Internal Server Error';
+    logError(`HTTP ${statusCode}: ${err.message} - ${req.method} ${req.path}`, err);
+    if (isFetchError && err.code === 'RATE_LIMITED' && err.details.retryAfter) {
+        const retryAfter = err.details.retryAfter;
+        res.set('Retry-After', String(retryAfter));
     }
     const response = {
         error: {
             message,
             code,
             statusCode,
+            ...(isFetchError &&
+                Object.keys(err.details).length > 0 && { details: err.details }),
         },
     };
-    if (err instanceof ValidationError && err.details) {
-        response.error.details = err.details;
-    }
     if (process.env.NODE_ENV === 'development') {
         response.error.stack = err.stack;
     }

package/dist/middleware/error-handler.js.map

@@ -1 +1 @@
-{"version":3,"file":"error-handler.js","sourceRoot":"","sources":["../../src/middleware/error-handler.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAE/E,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAEjD,MAAM,UAAU,YAAY,CAC1B,GAAU,EACV,IAAa,EACb,GAAa;AACb,4GAA4G;AAC5G,KAAmB;IAEnB,MAAM,UAAU,GAAG,GAAG,YAAY,QAAQ,CAAC;IAC3C,MAAM,UAAU,GAAG,UAAU,CAAC,CAAC,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,CAAC;IACrD,MAAM,IAAI,GAAG,UAAU,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,gBAAgB,CAAC;IACtD,MAAM,OAAO,GACX,UAAU,IAAI,GAAG,CAAC,aAAa,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,uBAAuB,CAAC;IAE1E,QAAQ,CAAC,QAAQ,UAAU,KAAK,GAAG,CAAC,OAAO,EAAE,EAAE,GAAG,CAAC,CAAC;IAEpD,IAAI,GAAG,YAAY,cAAc,EAAE,CAAC;QAClC,GAAG,CAAC,GAAG,CAAC,aAAa,EAAE,MAAM,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC;IACjD,CAAC;IAED,MAAM,QAAQ,GAAkB;QAC9B,KAAK,EAAE;YACL,OAAO;YACP,IAAI;YACJ,UAAU;SACX;KACF,CAAC;IAEF,IAAI,GAAG,YAAY,eAAe,IAAI,GAAG,CAAC,OAAO,EAAE,CAAC;QAClD,QAAQ,CAAC,KAAK,CAAC,OAAO,GAAG,GAAG,CAAC,OAAO,CAAC;IACvC,CAAC;IAED,IAAI,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,aAAa,EAAE,CAAC;QAC3C,QAAQ,CAAC,KAAK,CAAC,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC;IACnC,CAAC;IAED,GAAG,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;AACxC,CAAC"}
+{"version":3,"file":"error-handler.js","sourceRoot":"","sources":["../../src/middleware/error-handler.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAEpD,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAEjD,MAAM,UAAU,YAAY,CAAC,GAAU,EAAE,GAAY,EAAE,GAAa;IAClE,MAAM,YAAY,GAAG,GAAG,YAAY,UAAU,CAAC;IAC/C,MAAM,UAAU,GAAG,YAAY,CAAC,CAAC,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,CAAC;IACvD,MAAM,IAAI,GAAG,YAAY,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,gBAAgB,CAAC;IACxD,MAAM,OAAO,GAAG,YAAY,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,uBAAuB,CAAC;IAErE,QAAQ,CACN,QAAQ,UAAU,KAAK,GAAG,CAAC,OAAO,MAAM,GAAG,CAAC,MAAM,IAAI,GAAG,CAAC,IAAI,EAAE,EAChE,GAAG,CACJ,CAAC;IAEF,IAAI,YAAY,IAAI,GAAG,CAAC,IAAI,KAAK,cAAc,IAAI,GAAG,CAAC,OAAO,CAAC,UAAU,EAAE,CAAC;QAC1E,MAAM,UAAU,GAAG,GAAG,CAAC,OAAO,CAAC,UAAoB,CAAC;QACpD,GAAG,CAAC,GAAG,CAAC,aAAa,EAAE,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC;IAC7C,CAAC;IAED,MAAM,QAAQ,GAAkB;QAC9B,KAAK,EAAE;YACL,OAAO;YACP,IAAI;YACJ,UAAU;YACV,GAAG,CAAC,YAAY;gBACd,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE,CAAC;SACnE;KACF,CAAC;IAEF,IAAI,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,aAAa,EAAE,CAAC;QAC3C,QAAQ,CAAC,KAAK,CAAC,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC;IACnC,CAAC;IAED,GAAG,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;AACxC,CAAC"}

package/dist/middleware/rate-limiter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rate-limiter.d.ts","sourceRoot":"","sources":["../../src/middleware/rate-limiter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAE/D,OAAO,KAAK,EAAkB,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAa7E,cAAM,WAAW;IACf,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAqC;IAC3D,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,eAAe,CAA+C;gBAE1D,OAAO,GAAE,OAAO,CAAC,kBAAkB,CAAM;IAmBrD,OAAO,IAAI,IAAI;IAQf,UAAU,IAAI,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,YAAY,KAAK,IAAI;IAqCvE,OAAO,CAAC,MAAM;IAiBd,OAAO,CAAC,OAAO;CAUhB;AAID,eAAO,MAAM,WAAW,aAGtB,CAAC"}
+{"version":3,"file":"rate-limiter.d.ts","sourceRoot":"","sources":["../../src/middleware/rate-limiter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAE/D,OAAO,KAAK,EAAkB,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAoB7E,cAAM,WAAW;IACf,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAqC;IAC3D,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,eAAe,CAA+C;gBAE1D,OAAO,GAAE,OAAO,CAAC,kBAAkB,CAAM;IAmBrD,OAAO,IAAI,IAAI;IAQf,UAAU,IAAI,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,YAAY,KAAK,IAAI;IA8CvE,OAAO,CAAC,MAAM;IAwBd,OAAO,CAAC,OAAO;CAUhB;AAED,eAAO,MAAM,WAAW,aAGtB,CAAC"}

package/dist/middleware/rate-limiter.js

@@ -7,6 +7,10 @@ const MIN_MAX_REQUESTS = 1;
 const MAX_MAX_REQUESTS = 10000;
 const MIN_WINDOW_MS = 1000;
 const MAX_WINDOW_MS = 3600000;
+const TRUSTED_PROXIES = new Set((process.env.TRUSTED_PROXIES ?? '')
+    .split(',')
+    .map((ip) => ip.trim())
+    .filter(Boolean));
 class RateLimiter {
     store = new Map();
     maxRequests;
@@ -36,14 +40,25 @@ class RateLimiter {
             let entry = this.store.get(key);
             if (!entry || now > entry.resetTime) {
                 entry = {
-                    count: 0,
+                    count: 1,
                     resetTime: now + this.windowMs,
                     lastAccessed: now,
                 };
                 this.store.set(key, entry);
             }
-            entry.count++;
-            entry.lastAccessed = now;
+            else {
+                if (entry.count >= this.maxRequests) {
+                    const retryAfter = Math.ceil((entry.resetTime - now) / 1000);
+                    res.set('Retry-After', String(retryAfter));
+                    res.status(429).json({
+                        error: 'Too many requests',
+                        retryAfter,
+                    });
+                    return;
+                }
+                entry.count++;
+                entry.lastAccessed = now;
+            }
             if (entry.count > this.maxRequests) {
                 const retryAfter = Math.ceil((entry.resetTime - now) / 1000);
                 res.set('Retry-After', String(retryAfter));
@@ -61,16 +76,20 @@ class RateLimiter {
     }
     getKey(req) {
         const fallback = req.ip ?? req.socket.remoteAddress ?? 'unknown';
-        const realIp = req.headers['x-real-ip'];
-        const forwardedFor = req.headers['x-forwarded-for'];
+        const sourceIp = req.socket.remoteAddress ?? '';
+        const isTrustedProxy = TRUSTED_PROXIES.size === 0 || TRUSTED_PROXIES.has(sourceIp);
         let ip = fallback;
-        if (typeof realIp === 'string' && realIp) {
-            ip = realIp;
-        }
-        else if (typeof forwardedFor === 'string') {
-            const firstIp = forwardedFor.split(',')[0]?.trim();
-            if (firstIp)
-                ip = firstIp;
+        if (isTrustedProxy) {
+            const realIp = req.headers['x-real-ip'];
+            const forwardedFor = req.headers['x-forwarded-for'];
+            if (typeof realIp === 'string' && realIp) {
+                ip = realIp;
+            }
+            else if (typeof forwardedFor === 'string') {
+                const firstIp = forwardedFor.split(',')[0]?.trim();
+                if (firstIp)
+                    ip = firstIp;
+            }
         }
         const sanitized = ip.replace(/[^a-fA-F0-9.:]/g, '').substring(0, 45);
         return sanitized.length > 0 ? sanitized : 'unknown';
@@ -85,8 +104,6 @@ class RateLimiter {
         }
     }
 }
-// Create default rate limiter instance
-// Override via RateLimiter constructor if different values needed
 export const rateLimiter = new RateLimiter({
     maxRequests: 100,
     windowMs: 60000,

package/dist/middleware/rate-limiter.js.map

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

package/dist/parsers/base-html-element-parser.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Base class for HTML element parsers that extract specific content types.
+ * Provides common selector querying and attribute extraction functionality.
+ */
+export declare abstract class BaseHTMLElementParser<T> {
+    /**
+     * Parse HTML content and extract structured data.
+     * @param document - The JSDOM document to parse
+     * @returns Parsed data of type T or null if extraction fails
+     */
+    abstract parse(document: Document): T | null;
+    /**
+     * Validate the parsed data conforms to expected type.
+     * @param data - The data to validate
+     * @returns True if data is valid
+     */
+    protected isValidData(data: T | null): data is T;
+    /**
+     * Query a single element using CSS selector.
+     */
+    protected querySelector(parent: Document | Element, selector: string): Element | null;
+    /**
+     * Query multiple elements using CSS selector.
+     */
+    protected querySelectorAll(parent: Document | Element, selector: string): Element[];
+    /**
+     * Safely extract text content from an element.
+     */
+    protected getTextContent(element: Element | null): string | undefined;
+    /**
+     * Safely extract attribute value from an element.
+     */
+    protected getAttribute(element: Element | null, attr: string): string | undefined;
+    /**
+     * Extract multiple attributes from an element.
+     */
+    protected getAttributes(element: Element | null, attrs: string[]): Record<string, string>;
+    /**
+     * Check if element exists and has content.
+     */
+    protected hasContent(element: Element | null): boolean;
+}
+//# sourceMappingURL=base-html-element-parser.d.ts.map

package/dist/parsers/base-html-element-parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-html-element-parser.d.ts","sourceRoot":"","sources":["../../src/parsers/base-html-element-parser.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,8BAAsB,qBAAqB,CAAC,CAAC;IAC3C;;;;OAIG;IACH,QAAQ,CAAC,KAAK,CAAC,QAAQ,EAAE,QAAQ,GAAG,CAAC,GAAG,IAAI;IAE5C;;;;OAIG;IACH,SAAS,CAAC,WAAW,CAAC,IAAI,EAAE,CAAC,GAAG,IAAI,GAAG,IAAI,IAAI,CAAC;IAIhD;;OAEG;IACH,SAAS,CAAC,aAAa,CACrB,MAAM,EAAE,QAAQ,GAAG,OAAO,EAC1B,QAAQ,EAAE,MAAM,GACf,OAAO,GAAG,IAAI;IAIjB;;OAEG;IACH,SAAS,CAAC,gBAAgB,CACxB,MAAM,EAAE,QAAQ,GAAG,OAAO,EAC1B,QAAQ,EAAE,MAAM,GACf,OAAO,EAAE;IAIZ;;OAEG;IACH,SAAS,CAAC,cAAc,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,GAAG,MAAM,GAAG,SAAS;IAIrE;;OAEG;IACH,SAAS,CAAC,YAAY,CACpB,OAAO,EAAE,OAAO,GAAG,IAAI,EACvB,IAAI,EAAE,MAAM,GACX,MAAM,GAAG,SAAS;IAIrB;;OAEG;IACH,SAAS,CAAC,aAAa,CACrB,OAAO,EAAE,OAAO,GAAG,IAAI,EACvB,KAAK,EAAE,MAAM,EAAE,GACd,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAWzB;;OAEG;IACH,SAAS,CAAC,UAAU,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,GAAG,OAAO;CAGvD"}

package/dist/parsers/base-html-element-parser.js

@@ -0,0 +1,59 @@
+/**
+ * Base class for HTML element parsers that extract specific content types.
+ * Provides common selector querying and attribute extraction functionality.
+ */
+export class BaseHTMLElementParser {
+    /**
+     * Validate the parsed data conforms to expected type.
+     * @param data - The data to validate
+     * @returns True if data is valid
+     */
+    isValidData(data) {
+        return data !== null;
+    }
+    /**
+     * Query a single element using CSS selector.
+     */
+    querySelector(parent, selector) {
+        return parent.querySelector(selector);
+    }
+    /**
+     * Query multiple elements using CSS selector.
+     */
+    querySelectorAll(parent, selector) {
+        return Array.from(parent.querySelectorAll(selector));
+    }
+    /**
+     * Safely extract text content from an element.
+     */
+    getTextContent(element) {
+        return element?.textContent.trim() ?? undefined;
+    }
+    /**
+     * Safely extract attribute value from an element.
+     */
+    getAttribute(element, attr) {
+        return element?.getAttribute(attr)?.trim() ?? undefined;
+    }
+    /**
+     * Extract multiple attributes from an element.
+     */
+    getAttributes(element, attrs) {
+        const result = {};
+        if (!element)
+            return result;
+        for (const attr of attrs) {
+            const value = this.getAttribute(element, attr);
+            if (value)
+                result[attr] = value;
+        }
+        return result;
+    }
+    /**
+     * Check if element exists and has content.
+     */
+    hasContent(element) {
+        return !!element && !!element.textContent.trim();
+    }
+}
+//# sourceMappingURL=base-html-element-parser.js.map

package/dist/parsers/base-html-element-parser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-html-element-parser.js","sourceRoot":"","sources":["../../src/parsers/base-html-element-parser.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,OAAgB,qBAAqB;IAQzC;;;;OAIG;IACO,WAAW,CAAC,IAAc;QAClC,OAAO,IAAI,KAAK,IAAI,CAAC;IACvB,CAAC;IAED;;OAEG;IACO,aAAa,CACrB,MAA0B,EAC1B,QAAgB;QAEhB,OAAO,MAAM,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAC;IACxC,CAAC;IAED;;OAEG;IACO,gBAAgB,CACxB,MAA0B,EAC1B,QAAgB;QAEhB,OAAO,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,gBAAgB,CAAC,QAAQ,CAAC,CAAC,CAAC;IACvD,CAAC;IAED;;OAEG;IACO,cAAc,CAAC,OAAuB;QAC9C,OAAO,OAAO,EAAE,WAAW,CAAC,IAAI,EAAE,IAAI,SAAS,CAAC;IAClD,CAAC;IAED;;OAEG;IACO,YAAY,CACpB,OAAuB,EACvB,IAAY;QAEZ,OAAO,OAAO,EAAE,YAAY,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,IAAI,SAAS,CAAC;IAC1D,CAAC;IAED;;OAEG;IACO,aAAa,CACrB,OAAuB,EACvB,KAAe;QAEf,MAAM,MAAM,GAA2B,EAAE,CAAC;QAC1C,IAAI,CAAC,OAAO;YAAE,OAAO,MAAM,CAAC;QAE5B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,MAAM,KAAK,GAAG,IAAI,CAAC,YAAY,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;YAC/C,IAAI,KAAK;gBAAE,MAAM,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC;QAClC,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IAED;;OAEG;IACO,UAAU,CAAC,OAAuB;QAC1C,OAAO,CAAC,CAAC,OAAO,IAAI,CAAC,CAAC,OAAO,CAAC,WAAW,CAAC,IAAI,EAAE,CAAC;IACnD,CAAC;CACF"}

package/dist/parsers/heading-element-parser.d.ts

@@ -0,0 +1,14 @@
+import { BaseHTMLElementParser } from './base-html-element-parser.js';
+interface HeadingData {
+    level: number;
+    text: string;
+    id?: string;
+}
+/**
+ * Parser for HTML heading elements (h1-h6) with hierarchy.
+ */
+export declare class HeadingElementParser extends BaseHTMLElementParser<HeadingData[]> {
+    parse(document: Document): HeadingData[] | null;
+}
+export {};
+//# sourceMappingURL=heading-element-parser.d.ts.map

package/dist/parsers/heading-element-parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"heading-element-parser.d.ts","sourceRoot":"","sources":["../../src/parsers/heading-element-parser.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AAEtE,UAAU,WAAW;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,CAAC,EAAE,MAAM,CAAC;CACb;AAED;;GAEG;AACH,qBAAa,oBAAqB,SAAQ,qBAAqB,CAAC,WAAW,EAAE,CAAC;IAC5E,KAAK,CAAC,QAAQ,EAAE,QAAQ,GAAG,WAAW,EAAE,GAAG,IAAI;CAuBhD"}

package/dist/parsers/heading-element-parser.js

@@ -0,0 +1,26 @@
+import { BaseHTMLElementParser } from './base-html-element-parser.js';
+/**
+ * Parser for HTML heading elements (h1-h6) with hierarchy.
+ */
+export class HeadingElementParser extends BaseHTMLElementParser {
+    parse(document) {
+        const headings = [];
+        // Extract all heading elements
+        for (let level = 1; level <= 6; level++) {
+            const elements = this.querySelectorAll(document, `h${level}`);
+            for (const el of elements) {
+                const text = this.getTextContent(el);
+                if (!text)
+                    continue;
+                const heading = { level, text };
+                // Optional id attribute
+                const id = this.getAttribute(el, 'id');
+                if (id)
+                    heading.id = id;
+                headings.push(heading);
+            }
+        }
+        return headings.length > 0 ? headings : null;
+    }
+}
+//# sourceMappingURL=heading-element-parser.js.map

package/dist/parsers/heading-element-parser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"heading-element-parser.js","sourceRoot":"","sources":["../../src/parsers/heading-element-parser.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AAQtE;;GAEG;AACH,MAAM,OAAO,oBAAqB,SAAQ,qBAAoC;IAC5E,KAAK,CAAC,QAAkB;QACtB,MAAM,QAAQ,GAAkB,EAAE,CAAC;QAEnC,+BAA+B;QAC/B,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,IAAI,CAAC,EAAE,KAAK,EAAE,EAAE,CAAC;YACxC,MAAM,QAAQ,GAAG,IAAI,CAAC,gBAAgB,CAAC,QAAQ,EAAE,IAAI,KAAK,EAAE,CAAC,CAAC;YAE9D,KAAK,MAAM,EAAE,IAAI,QAAQ,EAAE,CAAC;gBAC1B,MAAM,IAAI,GAAG,IAAI,CAAC,cAAc,CAAC,EAAE,CAAC,CAAC;gBACrC,IAAI,CAAC,IAAI;oBAAE,SAAS;gBAEpB,MAAM,OAAO,GAAgB,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;gBAE7C,wBAAwB;gBACxB,MAAM,EAAE,GAAG,IAAI,CAAC,YAAY,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;gBACvC,IAAI,EAAE;oBAAE,OAAO,CAAC,EAAE,GAAG,EAAE,CAAC;gBAExB,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YACzB,CAAC;QACH,CAAC;QAED,OAAO,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC;IAC/C,CAAC;CACF"}

package/dist/parsers/image-element-parser.d.ts

@@ -0,0 +1,16 @@
+import { BaseHTMLElementParser } from './base-html-element-parser.js';
+interface ImageData {
+    src?: string;
+    alt?: string;
+    width?: string;
+    height?: string;
+    loading?: string;
+}
+/**
+ * Parser for HTML image elements with metadata.
+ */
+export declare class ImageElementParser extends BaseHTMLElementParser<ImageData[]> {
+    parse(document: Document): ImageData[] | null;
+}
+export {};
+//# sourceMappingURL=image-element-parser.d.ts.map

package/dist/parsers/image-element-parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"image-element-parser.d.ts","sourceRoot":"","sources":["../../src/parsers/image-element-parser.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AAEtE,UAAU,SAAS;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,qBAAqB,CAAC,SAAS,EAAE,CAAC;IACxE,KAAK,CAAC,QAAQ,EAAE,QAAQ,GAAG,SAAS,EAAE,GAAG,IAAI;CA8B9C"}

package/dist/parsers/image-element-parser.js

@@ -0,0 +1,33 @@
+import { BaseHTMLElementParser } from './base-html-element-parser.js';
+/**
+ * Parser for HTML image elements with metadata.
+ */
+export class ImageElementParser extends BaseHTMLElementParser {
+    parse(document) {
+        const images = [];
+        // Extract all img elements with src
+        const imgElements = this.querySelectorAll(document, 'img[src]');
+        for (const img of imgElements) {
+            const src = this.getAttribute(img, 'src');
+            if (!src)
+                continue;
+            const imageData = { src };
+            // Optional attributes
+            const alt = this.getAttribute(img, 'alt');
+            if (alt)
+                imageData.alt = alt;
+            const width = this.getAttribute(img, 'width');
+            if (width)
+                imageData.width = width;
+            const height = this.getAttribute(img, 'height');
+            if (height)
+                imageData.height = height;
+            const loading = this.getAttribute(img, 'loading');
+            if (loading)
+                imageData.loading = loading;
+            images.push(imageData);
+        }
+        return images.length > 0 ? images : null;
+    }
+}
+//# sourceMappingURL=image-element-parser.js.map

package/dist/parsers/image-element-parser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"image-element-parser.js","sourceRoot":"","sources":["../../src/parsers/image-element-parser.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AAUtE;;GAEG;AACH,MAAM,OAAO,kBAAmB,SAAQ,qBAAkC;IACxE,KAAK,CAAC,QAAkB;QACtB,MAAM,MAAM,GAAgB,EAAE,CAAC;QAE/B,oCAAoC;QACpC,MAAM,WAAW,GAAG,IAAI,CAAC,gBAAgB,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;QAEhE,KAAK,MAAM,GAAG,IAAI,WAAW,EAAE,CAAC;YAC9B,MAAM,GAAG,GAAG,IAAI,CAAC,YAAY,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;YAC1C,IAAI,CAAC,GAAG;gBAAE,SAAS;YAEnB,MAAM,SAAS,GAAc,EAAE,GAAG,EAAE,CAAC;YAErC,sBAAsB;YACtB,MAAM,GAAG,GAAG,IAAI,CAAC,YAAY,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;YAC1C,IAAI,GAAG;gBAAE,SAAS,CAAC,GAAG,GAAG,GAAG,CAAC;YAE7B,MAAM,KAAK,GAAG,IAAI,CAAC,YAAY,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;YAC9C,IAAI,KAAK;gBAAE,SAAS,CAAC,KAAK,GAAG,KAAK,CAAC;YAEnC,MAAM,MAAM,GAAG,IAAI,CAAC,YAAY,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;YAChD,IAAI,MAAM;gBAAE,SAAS,CAAC,MAAM,GAAG,MAAM,CAAC;YAEtC,MAAM,OAAO,GAAG,IAAI,CAAC,YAAY,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;YAClD,IAAI,OAAO;gBAAE,SAAS,CAAC,OAAO,GAAG,OAAO,CAAC;YAEzC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QACzB,CAAC;QAED,OAAO,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC;IAC3C,CAAC;CACF"}

package/dist/parsers/link-element-parser.d.ts

@@ -0,0 +1,15 @@
+import { BaseHTMLElementParser } from './base-html-element-parser.js';
+interface LinkData {
+    rel?: string;
+    href?: string;
+    type?: string;
+    title?: string;
+}
+/**
+ * Parser for HTML link elements (canonical, alternate, icon, etc.).
+ */
+export declare class LinkElementParser extends BaseHTMLElementParser<LinkData[]> {
+    parse(document: Document): LinkData[] | null;
+}
+export {};
+//# sourceMappingURL=link-element-parser.d.ts.map

package/dist/parsers/link-element-parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"link-element-parser.d.ts","sourceRoot":"","sources":["../../src/parsers/link-element-parser.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AAEtE,UAAU,QAAQ;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,qBAAa,iBAAkB,SAAQ,qBAAqB,CAAC,QAAQ,EAAE,CAAC;IACtE,KAAK,CAAC,QAAQ,EAAE,QAAQ,GAAG,QAAQ,EAAE,GAAG,IAAI;CA0B7C"}

package/dist/parsers/link-element-parser.js

@@ -0,0 +1,28 @@
+import { BaseHTMLElementParser } from './base-html-element-parser.js';
+/**
+ * Parser for HTML link elements (canonical, alternate, icon, etc.).
+ */
+export class LinkElementParser extends BaseHTMLElementParser {
+    parse(document) {
+        const links = [];
+        // Extract all link elements with rel and href
+        const linkElements = this.querySelectorAll(document, 'link[rel][href]');
+        for (const link of linkElements) {
+            const rel = this.getAttribute(link, 'rel');
+            const href = this.getAttribute(link, 'href');
+            if (!rel || !href)
+                continue;
+            const linkData = { rel, href };
+            // Optional attributes
+            const type = this.getAttribute(link, 'type');
+            if (type)
+                linkData.type = type;
+            const title = this.getAttribute(link, 'title');
+            if (title)
+                linkData.title = title;
+            links.push(linkData);
+        }
+        return links.length > 0 ? links : null;
+    }
+}
+//# sourceMappingURL=link-element-parser.js.map

package/dist/parsers/link-element-parser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"link-element-parser.js","sourceRoot":"","sources":["../../src/parsers/link-element-parser.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AAStE;;GAEG;AACH,MAAM,OAAO,iBAAkB,SAAQ,qBAAiC;IACtE,KAAK,CAAC,QAAkB;QACtB,MAAM,KAAK,GAAe,EAAE,CAAC;QAE7B,8CAA8C;QAC9C,MAAM,YAAY,GAAG,IAAI,CAAC,gBAAgB,CAAC,QAAQ,EAAE,iBAAiB,CAAC,CAAC;QAExE,KAAK,MAAM,IAAI,IAAI,YAAY,EAAE,CAAC;YAChC,MAAM,GAAG,GAAG,IAAI,CAAC,YAAY,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;YAC3C,MAAM,IAAI,GAAG,IAAI,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;YAE7C,IAAI,CAAC,GAAG,IAAI,CAAC,IAAI;gBAAE,SAAS;YAE5B,MAAM,QAAQ,GAAa,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC;YAEzC,sBAAsB;YACtB,MAAM,IAAI,GAAG,IAAI,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;YAC7C,IAAI,IAAI;gBAAE,QAAQ,CAAC,IAAI,GAAG,IAAI,CAAC;YAE/B,MAAM,KAAK,GAAG,IAAI,CAAC,YAAY,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;YAC/C,IAAI,KAAK;gBAAE,QAAQ,CAAC,KAAK,GAAG,KAAK,CAAC;YAElC,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACvB,CAAC;QAED,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC;IACzC,CAAC;CACF"}

package/dist/parsers/open-graph-parser.d.ts

@@ -0,0 +1,17 @@
+import { BaseHTMLElementParser } from './base-html-element-parser.js';
+interface OpenGraphData {
+    title?: string;
+    description?: string;
+    image?: string;
+    url?: string;
+    siteName?: string;
+    type?: string;
+}
+/**
+ * Parser for Open Graph meta tags (og:*).
+ */
+export declare class OpenGraphParser extends BaseHTMLElementParser<OpenGraphData> {
+    parse(document: Document): OpenGraphData | null;
+}
+export {};
+//# sourceMappingURL=open-graph-parser.d.ts.map

package/dist/parsers/open-graph-parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"open-graph-parser.d.ts","sourceRoot":"","sources":["../../src/parsers/open-graph-parser.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AAEtE,UAAU,aAAa;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,qBAAa,eAAgB,SAAQ,qBAAqB,CAAC,aAAa,CAAC;IACvE,KAAK,CAAC,QAAQ,EAAE,QAAQ,GAAG,aAAa,GAAG,IAAI;CAuChD"}

package/dist/parsers/open-graph-parser.js

@@ -0,0 +1,41 @@
+import { BaseHTMLElementParser } from './base-html-element-parser.js';
+/**
+ * Parser for Open Graph meta tags (og:*).
+ */
+export class OpenGraphParser extends BaseHTMLElementParser {
+    parse(document) {
+        const data = {};
+        // Extract all Open Graph meta tags
+        const ogTags = this.querySelectorAll(document, 'meta[property^="og:"]');
+        for (const tag of ogTags) {
+            const property = this.getAttribute(tag, 'property');
+            const content = this.getAttribute(tag, 'content');
+            if (!property || !content)
+                continue;
+            // Extract property name (e.g., "og:title" → "title")
+            const key = property.replace('og:', '');
+            switch (key) {
+                case 'title':
+                    data.title = content;
+                    break;
+                case 'description':
+                    data.description = content;
+                    break;
+                case 'image':
+                    data.image = content;
+                    break;
+                case 'url':
+                    data.url = content;
+                    break;
+                case 'site_name':
+                    data.siteName = content;
+                    break;
+                case 'type':
+                    data.type = content;
+                    break;
+            }
+        }
+        return Object.keys(data).length > 0 ? data : null;
+    }
+}
+//# sourceMappingURL=open-graph-parser.js.map

package/dist/parsers/open-graph-parser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"open-graph-parser.js","sourceRoot":"","sources":["../../src/parsers/open-graph-parser.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AAWtE;;GAEG;AACH,MAAM,OAAO,eAAgB,SAAQ,qBAAoC;IACvE,KAAK,CAAC,QAAkB;QACtB,MAAM,IAAI,GAAkB,EAAE,CAAC;QAE/B,mCAAmC;QACnC,MAAM,MAAM,GAAG,IAAI,CAAC,gBAAgB,CAAC,QAAQ,EAAE,uBAAuB,CAAC,CAAC;QAExE,KAAK,MAAM,GAAG,IAAI,MAAM,EAAE,CAAC;YACzB,MAAM,QAAQ,GAAG,IAAI,CAAC,YAAY,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC;YACpD,MAAM,OAAO,GAAG,IAAI,CAAC,YAAY,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;YAElD,IAAI,CAAC,QAAQ,IAAI,CAAC,OAAO;gBAAE,SAAS;YAEpC,qDAAqD;YACrD,MAAM,GAAG,GAAG,QAAQ,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;YAExC,QAAQ,GAAG,EAAE,CAAC;gBACZ,KAAK,OAAO;oBACV,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC;oBACrB,MAAM;gBACR,KAAK,aAAa;oBAChB,IAAI,CAAC,WAAW,GAAG,OAAO,CAAC;oBAC3B,MAAM;gBACR,KAAK,OAAO;oBACV,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC;oBACrB,MAAM;gBACR,KAAK,KAAK;oBACR,IAAI,CAAC,GAAG,GAAG,OAAO,CAAC;oBACnB,MAAM;gBACR,KAAK,WAAW;oBACd,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC;oBACxB,MAAM;gBACR,KAAK,MAAM;oBACT,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC;oBACpB,MAAM;YACV,CAAC;QACH,CAAC;QAED,OAAO,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;IACpD,CAAC;CACF"}

package/dist/parsers/schema-org-parser.d.ts

@@ -0,0 +1,17 @@
+import { BaseHTMLElementParser } from './base-html-element-parser.js';
+interface SchemaOrgData {
+    type?: string;
+    name?: string;
+    description?: string;
+    image?: string;
+    url?: string;
+    [key: string]: unknown;
+}
+/**
+ * Parser for JSON-LD Schema.org structured data.
+ */
+export declare class SchemaOrgParser extends BaseHTMLElementParser<SchemaOrgData[]> {
+    parse(document: Document): SchemaOrgData[] | null;
+}
+export {};
+//# sourceMappingURL=schema-org-parser.d.ts.map

package/dist/parsers/schema-org-parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-org-parser.d.ts","sourceRoot":"","sources":["../../src/parsers/schema-org-parser.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AAEtE,UAAU,aAAa;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;GAEG;AACH,qBAAa,eAAgB,SAAQ,qBAAqB,CAAC,aAAa,EAAE,CAAC;IACzE,KAAK,CAAC,QAAQ,EAAE,QAAQ,GAAG,aAAa,EAAE,GAAG,IAAI;CA8BlD"}

package/dist/parsers/schema-org-parser.js

@@ -0,0 +1,32 @@
+import { BaseHTMLElementParser } from './base-html-element-parser.js';
+/**
+ * Parser for JSON-LD Schema.org structured data.
+ */
+export class SchemaOrgParser extends BaseHTMLElementParser {
+    parse(document) {
+        const results = [];
+        // Find all JSON-LD script tags
+        const scripts = this.querySelectorAll(document, 'script[type="application/ld+json"]');
+        for (const script of scripts) {
+            const textContent = this.getTextContent(script);
+            if (!textContent)
+                continue;
+            try {
+                const data = JSON.parse(textContent);
+                // Handle both single objects and arrays
+                if (Array.isArray(data)) {
+                    results.push(...data);
+                }
+                else {
+                    results.push(data);
+                }
+            }
+            catch {
+                // Skip invalid JSON
+                continue;
+            }
+        }
+        return results.length > 0 ? results : null;
+    }
+}
+//# sourceMappingURL=schema-org-parser.js.map

package/dist/parsers/schema-org-parser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-org-parser.js","sourceRoot":"","sources":["../../src/parsers/schema-org-parser.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AAWtE;;GAEG;AACH,MAAM,OAAO,eAAgB,SAAQ,qBAAsC;IACzE,KAAK,CAAC,QAAkB;QACtB,MAAM,OAAO,GAAoB,EAAE,CAAC;QAEpC,+BAA+B;QAC/B,MAAM,OAAO,GAAG,IAAI,CAAC,gBAAgB,CACnC,QAAQ,EACR,oCAAoC,CACrC,CAAC;QAEF,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;YAC7B,MAAM,WAAW,GAAG,IAAI,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC;YAChD,IAAI,CAAC,WAAW;gBAAE,SAAS;YAE3B,IAAI,CAAC;gBACH,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,WAAW,CAAoC,CAAC;gBAExE,wCAAwC;gBACxC,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;oBACxB,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,CAAC;gBACxB,CAAC;qBAAM,CAAC;oBACN,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;gBACrB,CAAC;YACH,CAAC;YAAC,MAAM,CAAC;gBACP,oBAAoB;gBACpB,SAAS;YACX,CAAC;QACH,CAAC;QAED,OAAO,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC;IAC7C,CAAC;CACF"}

package/dist/parsers/standard-meta-parser.d.ts

@@ -0,0 +1,18 @@
+import { BaseHTMLElementParser } from './base-html-element-parser.js';
+interface StandardMetadata {
+    title?: string;
+    description?: string;
+    keywords?: string;
+    author?: string;
+    viewport?: string;
+    charset?: string;
+    [key: string]: string | undefined;
+}
+/**
+ * Parser for standard HTML meta tags (name="*" and charset).
+ */
+export declare class StandardMetaParser extends BaseHTMLElementParser<StandardMetadata> {
+    parse(document: Document): StandardMetadata | null;
+}
+export {};
+//# sourceMappingURL=standard-meta-parser.d.ts.map

package/dist/parsers/standard-meta-parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"standard-meta-parser.d.ts","sourceRoot":"","sources":["../../src/parsers/standard-meta-parser.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AAEtE,UAAU,gBAAgB;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;CACnC;AAED;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,qBAAqB,CAAC,gBAAgB,CAAC;IAC7E,KAAK,CAAC,QAAQ,EAAE,QAAQ,GAAG,gBAAgB,GAAG,IAAI;CA+BnD"}

package/dist/parsers/standard-meta-parser.js

@@ -0,0 +1,32 @@
+import { BaseHTMLElementParser } from './base-html-element-parser.js';
+/**
+ * Parser for standard HTML meta tags (name="*" and charset).
+ */
+export class StandardMetaParser extends BaseHTMLElementParser {
+    parse(document) {
+        const data = {};
+        // Extract charset
+        const charsetMeta = this.querySelector(document, 'meta[charset]');
+        if (charsetMeta) {
+            data.charset = this.getAttribute(charsetMeta, 'charset');
+        }
+        // Extract standard meta tags
+        const metaTags = this.querySelectorAll(document, 'meta[name][content]');
+        for (const tag of metaTags) {
+            const name = this.getAttribute(tag, 'name');
+            const content = this.getAttribute(tag, 'content');
+            if (name && content) {
+                data[name] = content;
+            }
+        }
+        // Extract title if not already present
+        if (!data.title) {
+            const titleEl = this.querySelector(document, 'title');
+            if (titleEl) {
+                data.title = this.getTextContent(titleEl);
+            }
+        }
+        return Object.keys(data).length > 0 ? data : null;
+    }
+}
+//# sourceMappingURL=standard-meta-parser.js.map

package/dist/parsers/standard-meta-parser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"standard-meta-parser.js","sourceRoot":"","sources":["../../src/parsers/standard-meta-parser.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AAYtE;;GAEG;AACH,MAAM,OAAO,kBAAmB,SAAQ,qBAAuC;IAC7E,KAAK,CAAC,QAAkB;QACtB,MAAM,IAAI,GAAqB,EAAE,CAAC;QAElC,kBAAkB;QAClB,MAAM,WAAW,GAAG,IAAI,CAAC,aAAa,CAAC,QAAQ,EAAE,eAAe,CAAC,CAAC;QAClE,IAAI,WAAW,EAAE,CAAC;YAChB,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,YAAY,CAAC,WAAW,EAAE,SAAS,CAAC,CAAC;QAC3D,CAAC;QAED,6BAA6B;QAC7B,MAAM,QAAQ,GAAG,IAAI,CAAC,gBAAgB,CAAC,QAAQ,EAAE,qBAAqB,CAAC,CAAC;QAExE,KAAK,MAAM,GAAG,IAAI,QAAQ,EAAE,CAAC;YAC3B,MAAM,IAAI,GAAG,IAAI,CAAC,YAAY,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;YAC5C,MAAM,OAAO,GAAG,IAAI,CAAC,YAAY,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;YAElD,IAAI,IAAI,IAAI,OAAO,EAAE,CAAC;gBACpB,IAAI,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC;YACvB,CAAC;QACH,CAAC;QAED,uCAAuC;QACvC,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC;YAChB,MAAM,OAAO,GAAG,IAAI,CAAC,aAAa,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;YACtD,IAAI,OAAO,EAAE,CAAC;gBACZ,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC;YAC5C,CAAC;QACH,CAAC;QAED,OAAO,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;IACpD,CAAC;CACF"}