@songmu/mdhq 0.0.2

package/dist/config/config.js

@@ -0,0 +1,170 @@
+import os from "node:os";
+import path from "node:path";
+import { readFile } from "node:fs/promises";
+import { z } from "zod";
+import { MdhqError } from "../errors.js";
+const pathConfigSchema = z
+    .object({
+    entryQueryKey: z.string().nullable().optional()
+})
+    .passthrough();
+const hostConfigSchema = pathConfigSchema
+    .extend({
+    paths: z.record(z.string(), pathConfigSchema).optional()
+})
+    .passthrough();
+const frontmatterSchema = z
+    .object({
+    exclude: z.array(z.string()).optional(),
+    values: z.record(z.string(), z.union([z.string(), z.number(), z.boolean(), z.null()])).optional()
+})
+    .passthrough();
+const defuddleSchema = z
+    .object({
+    debug: z.boolean().optional(),
+    removeExactSelectors: z.boolean().optional(),
+    removePartialSelectors: z.boolean().optional(),
+    removeImages: z.boolean().optional(),
+    useAsync: z.boolean().optional(),
+    removeHiddenElements: z.boolean().optional(),
+    removeLowScoring: z.boolean().optional(),
+    removeSmallImages: z.boolean().optional(),
+    standardize: z.boolean().optional(),
+    removeContentPatterns: z.boolean().optional(),
+    contentSelector: z.string().optional(),
+    language: z.string().optional(),
+    includeReplies: z.union([z.boolean(), z.literal("extractors")]).optional(),
+    profile: z.boolean().optional()
+})
+    .passthrough();
+const configSchema = z
+    .object({
+    root: z.string().optional(),
+    userAgent: z.string().optional(),
+    timeoutMs: z.number().int().positive().optional(),
+    maxResponseBytes: z.number().int().positive().optional(),
+    maxRedirects: z.number().int().nonnegative().optional(),
+    assets: z.boolean().optional(),
+    useAsync: z.boolean().optional(),
+    defuddle: defuddleSchema.optional(),
+    frontmatter: frontmatterSchema.optional(),
+    hosts: z.record(z.string(), hostConfigSchema).optional()
+})
+    .passthrough();
+const KNOWN_TOP_LEVEL = new Set([
+    "root",
+    "userAgent",
+    "timeoutMs",
+    "maxResponseBytes",
+    "maxRedirects",
+    "assets",
+    "useAsync",
+    "defuddle",
+    "frontmatter",
+    "hosts"
+]);
+const KNOWN_FRONTMATTER = new Set(["exclude", "values"]);
+const KNOWN_HOST = new Set(["entryQueryKey", "paths"]);
+const KNOWN_PATH = new Set(["entryQueryKey"]);
+const KNOWN_DEFUDDLE = new Set([
+    "debug",
+    "removeExactSelectors",
+    "removePartialSelectors",
+    "removeImages",
+    "useAsync",
+    "removeHiddenElements",
+    "removeLowScoring",
+    "removeSmallImages",
+    "standardize",
+    "removeContentPatterns",
+    "contentSelector",
+    "language",
+    "includeReplies",
+    "profile"
+]);
+function warnUnknown(object, known, location, warnings) {
+    for (const key of Object.keys(object)) {
+        if (!known.has(key)) {
+            warnings.push({
+                code: "UNKNOWN_CONFIG_KEY",
+                message: `Unknown configuration key: ${location}${key}`
+            });
+        }
+    }
+}
+function collectUnknownWarnings(value) {
+    const warnings = [];
+    warnUnknown(value, KNOWN_TOP_LEVEL, "", warnings);
+    const frontmatter = value.frontmatter;
+    if (frontmatter && typeof frontmatter === "object" && !Array.isArray(frontmatter)) {
+        warnUnknown(frontmatter, KNOWN_FRONTMATTER, "frontmatter.", warnings);
+    }
+    const defuddle = value.defuddle;
+    if (defuddle && typeof defuddle === "object" && !Array.isArray(defuddle)) {
+        warnUnknown(defuddle, KNOWN_DEFUDDLE, "defuddle.", warnings);
+    }
+    const hosts = value.hosts;
+    if (hosts && typeof hosts === "object" && !Array.isArray(hosts)) {
+        for (const [hostPattern, hostValue] of Object.entries(hosts)) {
+            if (!hostValue || typeof hostValue !== "object" || Array.isArray(hostValue)) {
+                continue;
+            }
+            const host = hostValue;
+            warnUnknown(host, KNOWN_HOST, `hosts.${hostPattern}.`, warnings);
+            const paths = host.paths;
+            if (paths && typeof paths === "object" && !Array.isArray(paths)) {
+                for (const [pathPattern, pathValue] of Object.entries(paths)) {
+                    if (pathValue && typeof pathValue === "object" && !Array.isArray(pathValue)) {
+                        warnUnknown(pathValue, KNOWN_PATH, `hosts.${hostPattern}.paths.${pathPattern}.`, warnings);
+                    }
+                }
+            }
+        }
+    }
+    return warnings;
+}
+export function defaultConfigPath(env = process.env) {
+    const configHome = env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config");
+    return path.join(configHome, "mdhq", "config.json");
+}
+export function defaultDataRoot(env = process.env) {
+    const dataHome = env.XDG_DATA_HOME || path.join(os.homedir(), ".local", "share");
+    return path.join(dataHome, "mdhq");
+}
+export function resolveRoot(cliRoot, config, env = process.env) {
+    return path.resolve(cliRoot || env.MDHQ_ROOT || config.root || defaultDataRoot(env));
+}
+export async function loadConfig(configPath = defaultConfigPath()) {
+    let source;
+    try {
+        source = await readFile(configPath, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return { config: {}, warnings: [] };
+        }
+        throw new MdhqError("CONFIG_ERROR", `Failed to read configuration: ${configPath}`, {
+            cause: error
+        });
+    }
+    let raw;
+    try {
+        raw = JSON.parse(source);
+    }
+    catch (error) {
+        throw new MdhqError("CONFIG_ERROR", `Invalid JSON configuration: ${configPath}`, {
+            cause: error
+        });
+    }
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+        throw new MdhqError("CONFIG_ERROR", "Configuration must be a JSON object");
+    }
+    const parsed = configSchema.safeParse(raw);
+    if (!parsed.success) {
+        throw new MdhqError("CONFIG_ERROR", z.prettifyError(parsed.error));
+    }
+    return {
+        config: parsed.data,
+        warnings: collectUnknownWarnings(raw)
+    };
+}

package/dist/config/match.d.ts

@@ -0,0 +1,7 @@
+export interface PathConfig {
+    entryQueryKey?: string | null;
+}
+export interface HostConfig extends PathConfig {
+    paths?: Record<string, PathConfig>;
+}
+export declare function resolveHostConfig(host: string, pathname: string, hosts: Record<string, HostConfig>): PathConfig | undefined;

package/dist/config/match.js

@@ -0,0 +1,101 @@
+import { domainToASCII } from "node:url";
+import { Minimatch } from "minimatch";
+import { MdhqError } from "../errors.js";
+function literalSpecificity(pattern) {
+    let count = 0;
+    let skippedUntil;
+    for (let index = 0; index < pattern.length; index += 1) {
+        const character = pattern[index];
+        if (character === undefined) {
+            continue;
+        }
+        if (character === "\\") {
+            if (skippedUntil === undefined && index + 1 < pattern.length) {
+                count += 1;
+            }
+            index += 1;
+            continue;
+        }
+        if (skippedUntil) {
+            if (character === skippedUntil) {
+                skippedUntil = undefined;
+            }
+            continue;
+        }
+        if (character === "[") {
+            skippedUntil = "]";
+        }
+        else if (character === "{") {
+            skippedUntil = "}";
+        }
+        else if ("!?+*@".includes(character) && pattern[index + 1] === "(") {
+            skippedUntil = ")";
+            index += 1;
+        }
+        else if (character !== "*" && character !== "?") {
+            count += 1;
+        }
+    }
+    return count;
+}
+function normalizeHostPattern(pattern) {
+    const lower = pattern.toLowerCase();
+    const portMatch = lower.match(/:(\d+)$/u);
+    const port = portMatch?.[1];
+    const hostname = portMatch ? lower.slice(0, -portMatch[0].length) : lower;
+    const normalized = hostname
+        .split(".")
+        .map((label) => /[*?[\]{}()!+@]/u.test(label) ? label : domainToASCII(label))
+        .join(".");
+    return port ? `${normalized}:${port}` : normalized;
+}
+function selectPattern(value, patterns, kind) {
+    const entries = Object.entries(patterns).map(([pattern, config]) => ({
+        pattern,
+        normalizedPattern: kind === "host" ? normalizeHostPattern(pattern) : pattern,
+        config
+    }));
+    const exact = entries.filter((entry) => entry.normalizedPattern === value);
+    if (exact.length > 1) {
+        throw new MdhqError("CONFIG_ERROR", `Ambiguous normalized ${kind} patterns: ${exact.map((entry) => entry.pattern).join(" and ")}`);
+    }
+    if (exact[0]) {
+        return exact[0].config;
+    }
+    const matches = entries
+        .filter((entry) => new Minimatch(entry.normalizedPattern, { dot: true }).match(value))
+        .map((entry) => ({
+        pattern: entry.pattern,
+        config: entry.config,
+        specificity: literalSpecificity(entry.normalizedPattern)
+    }))
+        .sort((a, b) => b.specificity - a.specificity);
+    if (matches.length < 1) {
+        return undefined;
+    }
+    const best = matches[0];
+    const ambiguous = matches.find((match, index) => index > 0 && match.specificity === best?.specificity);
+    if (ambiguous) {
+        throw new MdhqError("CONFIG_ERROR", `Ambiguous ${kind} patterns: ${best?.pattern} and ${ambiguous.pattern}`);
+    }
+    return best?.config;
+}
+export function resolveHostConfig(host, pathname, hosts) {
+    const hostConfig = selectPattern(host, hosts, "host");
+    if (!hostConfig) {
+        return undefined;
+    }
+    const pathConfig = hostConfig.paths
+        ? selectPattern(pathname, hostConfig.paths, "path")
+        : undefined;
+    if (pathConfig) {
+        return pathConfig.entryQueryKey === undefined
+            ? hostConfig.entryQueryKey === undefined
+                ? {}
+                : { entryQueryKey: hostConfig.entryQueryKey }
+            : pathConfig;
+    }
+    return hostConfig.entryQueryKey === undefined
+        ? {}
+        : { entryQueryKey: hostConfig.entryQueryKey };
+}

package/dist/convert/article-date.d.ts

@@ -0,0 +1,20 @@
+import { parseHTML } from "linkedom";
+export type ArticleDocument = ReturnType<typeof parseHTML>["document"];
+export declare function extractArticleDateFromDocument(document: ArticleDocument, options: ArticleDateOptions, pageUrl?: string): string | undefined;
+export interface ArticleDateOptions {
+    /** Schema.org JSON-LD property name, e.g. "datePublished" or "dateModified". */
+    schemaProperty: string;
+    /** `meta[property="..."]` names to check, in priority order. */
+    metaProperties: readonly string[];
+    /** `itemprop` microdata names to check, in priority order. */
+    itemprops: readonly string[];
+}
+/**
+ * Extracts and normalizes a source-article date (published or updated) from
+ * Schema.org JSON-LD, Open Graph/article meta tags, and microdata. JSON-LD
+ * candidates preserve their original value (string, number, or JSON-LD
+ * `@value` object/array) so numeric or JSON-LD forms are not lost before
+ * `normalizeSourceDate` can inspect them; malformed JSON-LD blocks are
+ * ignored rather than throwing.
+ */
+export declare function extractArticleDate(html: string, options: ArticleDateOptions, pageUrl?: string): string | undefined;

package/dist/convert/article-date.js

@@ -0,0 +1,255 @@
+import { parseHTML } from "linkedom";
+import { normalizeSourceDate } from "../date.js";
+const ARTICLE_LIKE_TYPES = new Set([
+    "CreativeWork",
+    "APIReference",
+    "Report",
+    "WebPage"
+]);
+function types(value) {
+    if (typeof value === "string") {
+        return [value];
+    }
+    return Array.isArray(value) ? value.filter((item) => typeof item === "string") : [];
+}
+function schemaTypeName(value) {
+    for (const prefix of ["https://schema.org/", "http://schema.org/"]) {
+        if (value.startsWith(prefix)) {
+            return value.slice(prefix.length);
+        }
+    }
+    return value;
+}
+function isArticleLikeType(value) {
+    const name = schemaTypeName(value);
+    return (ARTICLE_LIKE_TYPES.has(name) ||
+        name.endsWith("Article") ||
+        name.endsWith("Posting"));
+}
+function isPageType(value) {
+    const name = schemaTypeName(value);
+    return name === "WebPage" || name.endsWith("Page");
+}
+function collectJsonLdObjects(value, objects, seen = new Set()) {
+    if (Array.isArray(value)) {
+        for (const item of value) {
+            collectJsonLdObjects(item, objects, seen);
+        }
+        return;
+    }
+    if (!value || typeof value !== "object") {
+        return;
+    }
+    const object = value;
+    if (seen.has(object)) {
+        return;
+    }
+    seen.add(object);
+    objects.push(object);
+    if ("@graph" in object) {
+        collectJsonLdObjects(object["@graph"], objects, seen);
+    }
+    if ("mainEntity" in object) {
+        collectJsonLdObjects(object.mainEntity, objects, seen);
+    }
+}
+function referenceUrls(value, baseUrl) {
+    if (Array.isArray(value)) {
+        return value.flatMap((item) => referenceUrls(item, baseUrl));
+    }
+    if (typeof value === "string") {
+        try {
+            return [new URL(value, baseUrl).href];
+        }
+        catch {
+            return [];
+        }
+    }
+    if (!value || typeof value !== "object") {
+        return [];
+    }
+    const object = value;
+    return [
+        ...referenceUrls(object["@id"], baseUrl),
+        ...referenceUrls(object.url, baseUrl)
+    ];
+}
+function pageHref(pageUrl) {
+    if (!pageUrl) {
+        return undefined;
+    }
+    try {
+        const url = new URL(pageUrl);
+        url.hash = "";
+        return url.href;
+    }
+    catch {
+        return undefined;
+    }
+}
+function directlyMatchesPage(value, page, baseUrl) {
+    if (!page) {
+        return false;
+    }
+    return referenceUrls(value, baseUrl).some((reference) => {
+        const url = new URL(reference);
+        return !url.hash && url.href === page;
+    });
+}
+function identifiesPageDocument(value, page, baseUrl) {
+    if (!page) {
+        return false;
+    }
+    return referenceUrls(value, baseUrl).some((reference) => {
+        const url = new URL(reference);
+        url.hash = "";
+        return url.href === page;
+    });
+}
+function intersects(left, right) {
+    return left.some((value) => right.has(value));
+}
+function referencedObjects(value) {
+    if (Array.isArray(value)) {
+        return value.flatMap(referencedObjects);
+    }
+    return value && typeof value === "object"
+        ? [value]
+        : [];
+}
+function hasDateCandidate(value) {
+    return value !== undefined && value !== null;
+}
+function jsonLdDates(objects, pageUrl, schemaProperty) {
+    const page = pageHref(pageUrl);
+    const pageEntityIds = new Set(page ? [page] : []);
+    const primaryEntityIds = new Set();
+    const primaryEntityObjects = new Set();
+    for (const object of objects) {
+        const pageObject = types(object["@type"]).some(isPageType);
+        if ((pageObject && identifiesPageDocument(object["@id"], page, pageUrl)) ||
+            directlyMatchesPage(object.url, page, pageUrl)) {
+            for (const identifier of referenceUrls(object["@id"], pageUrl)) {
+                pageEntityIds.add(identifier);
+            }
+            for (const identifier of referenceUrls(object.mainEntity, pageUrl)) {
+                primaryEntityIds.add(identifier);
+            }
+            for (const entity of referencedObjects(object.mainEntity)) {
+                primaryEntityObjects.add(entity);
+            }
+        }
+    }
+    return objects
+        .flatMap((object, index) => {
+        if (!hasDateCandidate(object[schemaProperty]) ||
+            !types(object["@type"]).some(isArticleLikeType)) {
+            return [];
+        }
+        const names = types(object["@type"]).map(schemaTypeName);
+        const concreteArticle = names.some((name) => name.endsWith("Article") || name.endsWith("Posting"));
+        const identifiers = [
+            ...referenceUrls(object["@id"], pageUrl),
+            ...referenceUrls(object.url, pageUrl)
+        ];
+        const primary = identifiesPageDocument(object["@id"], page, pageUrl) ||
+            directlyMatchesPage(object.url, page, pageUrl) ||
+            primaryEntityObjects.has(object) ||
+            identifiesPageDocument(object.mainEntityOfPage, page, pageUrl) ||
+            intersects(referenceUrls(object.mainEntityOfPage, pageUrl), pageEntityIds) ||
+            intersects(identifiers, primaryEntityIds);
+        return [
+            {
+                date: object[schemaProperty],
+                score: (primary ? 100 : 0) + (concreteArticle ? 20 : 10),
+                index
+            }
+        ];
+    })
+        .sort((left, right) => right.score - left.score || left.index - right.index)
+        .map((candidate) => candidate.date);
+}
+function attributeValue(element, attributes) {
+    for (const attribute of attributes) {
+        const value = element?.getAttribute(attribute)?.trim();
+        if (value) {
+            return value;
+        }
+    }
+    return undefined;
+}
+export function extractArticleDateFromDocument(document, options, pageUrl) {
+    const objects = [];
+    for (const script of document.querySelectorAll("script[type]")) {
+        const mediaType = script.getAttribute("type")?.split(";", 1)[0]?.trim().toLowerCase() ?? "";
+        if (mediaType !== "application/ld+json") {
+            continue;
+        }
+        try {
+            collectJsonLdObjects(parseJsonLd(script.textContent ?? ""), objects);
+        }
+        catch {
+            // Ignore malformed blocks and continue with other metadata sources.
+        }
+    }
+    const metaCandidates = options.metaProperties.map((property) => attributeValue(document.querySelector(`meta[property="${property}"]`), ["content"]));
+    const microdataCandidates = options.itemprops.map((itemprop) => attributeValue(document.querySelector(`[itemprop~="${itemprop}"]`), ["datetime", "content"]));
+    for (const candidate of [
+        ...jsonLdDates(objects, pageUrl, options.schemaProperty),
+        ...metaCandidates,
+        ...microdataCandidates
+    ]) {
+        const normalized = normalizeSourceDate(candidate);
+        if (normalized) {
+            return normalized;
+        }
+    }
+    return undefined;
+}
+function parseJsonLd(source) {
+    let result = "";
+    let inString = false;
+    for (let index = 0; index < source.length; index += 1) {
+        const character = source.charAt(index);
+        if (character === '"') {
+            let backslashes = 0;
+            for (let previous = index - 1; previous >= 0 && source[previous] === "\\"; previous -= 1) {
+                backslashes += 1;
+            }
+            if (backslashes % 2 === 0) {
+                inString = !inString;
+            }
+            result += character;
+            continue;
+        }
+        if (inString) {
+            result += character;
+            continue;
+        }
+        if (character === "-" || /\d/u.test(character)) {
+            const match = source
+                .slice(index)
+                .match(/^-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?/u);
+            if (match) {
+                const token = match[0];
+                result += /^-?\d+$/u.test(token) ? `"${token}"` : token;
+                index += token.length - 1;
+                continue;
+            }
+        }
+        result += character;
+    }
+    return JSON.parse(result);
+}
+/**
+ * Extracts and normalizes a source-article date (published or updated) from
+ * Schema.org JSON-LD, Open Graph/article meta tags, and microdata. JSON-LD
+ * candidates preserve their original value (string, number, or JSON-LD
+ * `@value` object/array) so numeric or JSON-LD forms are not lost before
+ * `normalizeSourceDate` can inspect them; malformed JSON-LD blocks are
+ * ignored rather than throwing.
+ */
+export function extractArticleDate(html, options, pageUrl) {
+    const { document } = parseHTML(html);
+    return extractArticleDateFromDocument(document, options, pageUrl);
+}

package/dist/convert/convert-html.d.ts

@@ -0,0 +1,2 @@
+import type { ConvertedPage, ConvertHtmlOptions } from "../types.js";
+export declare function convertHtml(options: ConvertHtmlOptions): Promise<ConvertedPage>;

package/dist/convert/convert-html.js

@@ -0,0 +1,89 @@
+import { Defuddle } from "defuddle/node";
+import { parseHTML } from "linkedom";
+import { MdhqError } from "../errors.js";
+import { normalizeSourceDate } from "../date.js";
+import { extractPublishedDateFromDocument } from "./extract-published.js";
+import { extractUpdatedDateFromDocument } from "./extract-updated.js";
+function nonempty(value) {
+    return value?.trim() ? value.trim() : undefined;
+}
+function dateOnlyEvidence(document, expectedDate) {
+    const text = document.body?.textContent ?? "";
+    const candidates = [
+        ...text.matchAll(/\b(?:January|February|March|April|May|June|July|August|September|October|November|December|Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)\.?\s+\d{1,2},?\s+\d{4}\b/giu),
+        ...text.matchAll(/\b\d{1,2}\s+(?:January|February|March|April|May|June|July|August|September|October|November|December|Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)\.?,?\s+\d{4}\b/giu)
+    ];
+    for (const candidate of candidates) {
+        const normalized = normalizeSourceDate(candidate[0]);
+        if (normalized === expectedDate) {
+            return normalized;
+        }
+    }
+    return undefined;
+}
+export async function convertHtml(options) {
+    let url;
+    try {
+        url = options.url instanceof URL ? new URL(options.url.href) : new URL(options.url);
+    }
+    catch (error) {
+        throw new MdhqError("INVALID_URL", `Invalid base URL: ${String(options.url)}`, {
+            cause: error
+        });
+    }
+    try {
+        const { document } = parseHTML(options.html);
+        const updated = extractUpdatedDateFromDocument(document, url.href);
+        const publishedFromMetadata = extractPublishedDateFromDocument(document, url.href);
+        const result = await Defuddle(options.html, url.href, {
+            ...options.defuddle,
+            markdown: true,
+            useAsync: options.defuddle?.useAsync ?? true
+        });
+        const markdown = result.content?.trim();
+        if (!markdown) {
+            throw new MdhqError("CONVERSION_FAILED", `Defuddle returned no content for ${url.href}`);
+        }
+        const publishedFromDefuddle = normalizeSourceDate(nonempty(result.published));
+        const synthesizedMidnightDate = publishedFromMetadata === undefined &&
+            publishedFromDefuddle?.match(/^\d{4}-\d{2}-\d{2}T00:00:00(?:Z|\+00:00)$/u)
+            ? publishedFromDefuddle
+            : undefined;
+        const publishedDateOnlyEvidence = synthesizedMidnightDate === undefined
+            ? undefined
+            : dateOnlyEvidence(document, synthesizedMidnightDate.slice(0, 10));
+        const published = publishedFromMetadata ??
+            (synthesizedMidnightDate !== undefined &&
+                publishedDateOnlyEvidence === synthesizedMidnightDate.slice(0, 10)
+                ? publishedDateOnlyEvidence
+                : publishedFromDefuddle);
+        const metadata = {};
+        const stringFields = {
+            title: nonempty(result.title),
+            description: nonempty(result.description),
+            author: nonempty(result.author),
+            published,
+            updated,
+            site: nonempty(result.site),
+            domain: nonempty(result.domain),
+            language: nonempty(result.language),
+            image: nonempty(result.image),
+            favicon: nonempty(result.favicon)
+        };
+        for (const [key, value] of Object.entries(stringFields)) {
+            if (value !== undefined) {
+                metadata[key] = value;
+            }
+        }
+        if (result.wordCount > 0) {
+            metadata.wordCount = result.wordCount;
+        }
+        return { markdown, metadata };
+    }
+    catch (error) {
+        if (error instanceof MdhqError) {
+            throw error;
+        }
+        throw new MdhqError("CONVERSION_FAILED", `Failed to convert ${url.href}`, { cause: error });
+    }
+}

package/dist/convert/extract-published.d.ts

@@ -0,0 +1,12 @@
+import { type ArticleDocument } from "./article-date.js";
+/**
+ * Extracts and normalizes the article publication ("published") date from
+ * Schema.org `datePublished` JSON-LD, `article:published_time` /
+ * `og:published_time` meta tags, or `itemprop="datePublished"` microdata.
+ *
+ * This is attempted before falling back to Defuddle's own (string-only)
+ * `published` extraction, because Defuddle drops numeric or JSON-LD
+ * `@value`-shaped `datePublished` values instead of stringifying them.
+ */
+export declare function extractPublishedDate(html: string, pageUrl?: string): string | undefined;
+export declare function extractPublishedDateFromDocument(document: ArticleDocument, pageUrl?: string): string | undefined;

package/dist/convert/extract-published.js

@@ -0,0 +1,24 @@
+import { extractArticleDate, extractArticleDateFromDocument } from "./article-date.js";
+/**
+ * Extracts and normalizes the article publication ("published") date from
+ * Schema.org `datePublished` JSON-LD, `article:published_time` /
+ * `og:published_time` meta tags, or `itemprop="datePublished"` microdata.
+ *
+ * This is attempted before falling back to Defuddle's own (string-only)
+ * `published` extraction, because Defuddle drops numeric or JSON-LD
+ * `@value`-shaped `datePublished` values instead of stringifying them.
+ */
+export function extractPublishedDate(html, pageUrl) {
+    return extractArticleDate(html, {
+        schemaProperty: "datePublished",
+        metaProperties: ["article:published_time", "og:published_time"],
+        itemprops: ["datePublished"]
+    }, pageUrl);
+}
+export function extractPublishedDateFromDocument(document, pageUrl) {
+    return extractArticleDateFromDocument(document, {
+        schemaProperty: "datePublished",
+        metaProperties: ["article:published_time", "og:published_time"],
+        itemprops: ["datePublished"]
+    }, pageUrl);
+}