rehype-og-card 2.0.0 → 2.0.2

package/README.md

@@ -128,7 +128,7 @@ Expiration is calculated using the cached timestamp stored in the cache itself.
 User agent to use for fetching the OG metadata and images.
 
 - Type: `string`
-- Default: `"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0.0.0 Safari/537.36"`
+- Default: `"Mozilla/5.0 (compatible; rehype-og-card/2.0; +https://github.com/Robot-Inventor/rehype-og-card/; purpose=link-preview; twitterbot-compatible)"`
 
 ### `decoding`
 

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+import type { Plugin } from "unified";
+import type { RehypeOGCardOptions } from "./types.js";
+import type { Root } from "hast";
+/**
+ * Rehype plugin to create OG card from bare links.
+ * @param options Plugin options.
+ * @returns Transformer function.
+ */
+declare const rehypeOGCard: Plugin<[RehypeOGCardOptions | undefined], Root>;
+export default rehypeOGCard;
+export type { RehypeOGCardOptions };

package/dist/index.js

@@ -0,0 +1,160 @@
+import { convertTextToAnchorElement, createOGCard, isAnchorElement, isTextNode } from "./util/hast.js";
+import { checkFileExistsSync, createDirectorySync } from "./util/file.js";
+import { downloadImage, getOGData, isValidURL } from "./util/network.js";
+import { restoreBuildCache, restoreOGDataBuildCache, saveBuildCacheFile, saveOGDataBuildCache } from "./util/cache.js";
+import { isElement } from "hast-util-is-element";
+import path from "path";
+import { visitParents } from "unist-util-visit-parents";
+// eslint-disable-next-line no-magic-numbers
+const ONE_DAY_MS = 24 * 60 * 60 * 1000;
+// eslint-disable-next-line no-magic-numbers
+const DEFAULT_CACHE_MAX_AGE_MS = 30 * ONE_DAY_MS;
+const DEFAULT_OPTIONS = {
+    buildCache: false,
+    buildCacheMaxAge: DEFAULT_CACHE_MAX_AGE_MS,
+    buildCachePath: "./node_modules/.cache",
+    crawlerUserAgent: "Mozilla/5.0 (compatible; rehype-og-card/2.0; +https://github.com/Robot-Inventor/rehype-og-card/; purpose=link-preview; twitterbot-compatible)",
+    decoding: "async",
+    enableSameTextURLConversion: false,
+    excludeDomains: [],
+    loading: "lazy",
+    openInNewTab: false,
+    serverCache: true,
+    serverCacheMaxAge: DEFAULT_CACHE_MAX_AGE_MS,
+    serverCachePath: "./public",
+    shortenURL: true
+};
+/**
+ * Rehype plugin to create OG card from bare links.
+ * @param options Plugin options.
+ * @returns Transformer function.
+ */
+// eslint-disable-next-line max-lines-per-function, max-statements
+const rehypeOGCard = (options) => {
+    const mergedOptions = {
+        ...DEFAULT_OPTIONS,
+        ...options
+    };
+    if (mergedOptions.buildCache && !mergedOptions.serverCache) {
+        throw new Error("[rehype-og-card] `buildCache` option requires `serverCache` option to be enabled.");
+    }
+    mergedOptions.serverCachePath = path.posix.join(mergedOptions.serverCachePath, "./rehype-og-card/");
+    mergedOptions.buildCachePath = path.posix.join(mergedOptions.buildCachePath, "./rehype-og-card/");
+    const buildCacheExists = checkFileExistsSync(mergedOptions.buildCachePath);
+    if (mergedOptions.buildCache) {
+        if (buildCacheExists) {
+            restoreBuildCache(mergedOptions.buildCachePath, mergedOptions.serverCachePath, mergedOptions.buildCacheMaxAge);
+        }
+        else {
+            createDirectorySync(mergedOptions.buildCachePath);
+        }
+    }
+    /**
+     * Transform function to create OG card from bare links.
+     * @param tree Root node of the HAST tree.
+     */
+    // eslint-disable-next-line max-lines-per-function
+    const transform = async (tree) => {
+        const linkCardPromises = [];
+        // eslint-disable-next-line max-statements, max-lines-per-function
+        visitParents(tree, ["element", "text"], (node, ancestors) => {
+            let anchorNode = null;
+            const isBareLink = node.type === "text" && isValidURL(node.value.trim());
+            const isValidAnchor = isAnchorElement(node) && isValidURL(node.properties.href);
+            if (isBareLink) {
+                anchorNode = convertTextToAnchorElement(node);
+            }
+            else if (mergedOptions.enableSameTextURLConversion && isValidAnchor) {
+                const isSameTextURL = 
+                // eslint-disable-next-line no-magic-numbers
+                node.children.length === 1 &&
+                    node.children[0] &&
+                    isTextNode(node.children[0]) &&
+                    node.children[0].value.trim() === node.properties.href;
+                if (!isSameTextURL)
+                    return;
+                anchorNode = node;
+            }
+            else {
+                return;
+            }
+            // eslint-disable-next-line no-magic-numbers
+            const parent = ancestors[ancestors.length - 1];
+            if (!parent)
+                return;
+            if (!isElement(parent, "p"))
+                return;
+            const shouldSkip = ancestors.some((ancestor) => isElement(ancestor) && ["ul", "ol"].includes(ancestor.tagName));
+            if (shouldSkip)
+                return;
+            // eslint-disable-next-line no-magic-numbers
+            const isTheOnlyChild = parent.children.length === 1;
+            if (!isTheOnlyChild)
+                return;
+            const targetURL = new URL(anchorNode.properties.href);
+            if (mergedOptions.excludeDomains.includes(targetURL.hostname))
+                return;
+            // eslint-disable-next-line jsdoc/require-jsdoc, max-statements, max-lines-per-function
+            const linkCardPromise = async () => {
+                let OGData = mergedOptions.buildCache
+                    ? await restoreOGDataBuildCache(anchorNode.properties.href, mergedOptions.buildCachePath, mergedOptions.buildCacheMaxAge)
+                    : null;
+                if (!OGData) {
+                    OGData = await getOGData(anchorNode.properties.href, mergedOptions.crawlerUserAgent);
+                    if (!OGData)
+                        return;
+                    if (mergedOptions.buildCache) {
+                        void saveOGDataBuildCache(anchorNode.properties.href, OGData, mergedOptions.buildCachePath);
+                    }
+                }
+                if (OGData.OGImageURL && mergedOptions.serverCache) {
+                    const filename = await downloadImage({
+                        cacheMaxAge: mergedOptions.serverCacheMaxAge,
+                        directory: mergedOptions.serverCachePath,
+                        url: OGData.OGImageURL,
+                        userAgent: mergedOptions.crawlerUserAgent
+                    });
+                    if (filename) {
+                        OGData.OGImageURL = path.posix.join("/rehype-og-card", filename);
+                    }
+                    if (filename && mergedOptions.buildCache) {
+                        const downloadedFilePath = path.join(mergedOptions.serverCachePath, filename);
+                        const buildCachePath = path.join(mergedOptions.buildCachePath, filename);
+                        void saveBuildCacheFile(downloadedFilePath, buildCachePath);
+                    }
+                }
+                if (OGData.faviconURL && mergedOptions.serverCache) {
+                    const filename = await downloadImage({
+                        cacheMaxAge: mergedOptions.serverCacheMaxAge,
+                        directory: mergedOptions.serverCachePath,
+                        url: OGData.faviconURL,
+                        userAgent: mergedOptions.crawlerUserAgent
+                    });
+                    if (filename) {
+                        OGData.faviconURL = path.posix.join("/rehype-og-card", filename);
+                    }
+                    if (filename && mergedOptions.buildCache) {
+                        const downloadedFilePath = path.join(mergedOptions.serverCachePath, filename);
+                        const buildCachePath = path.join(mergedOptions.buildCachePath, filename);
+                        void saveBuildCacheFile(downloadedFilePath, buildCachePath);
+                    }
+                }
+                if (mergedOptions.shortenURL) {
+                    const shortenedURL = new URL(anchorNode.properties.href);
+                    OGData.displayURL = shortenedURL.hostname;
+                }
+                const OGCard = createOGCard(OGData, mergedOptions);
+                const index = parent.children.indexOf(node);
+                // eslint-disable-next-line no-magic-numbers
+                if (index === -1)
+                    return;
+                // eslint-disable-next-line no-magic-numbers
+                parent.children.splice(index, 1, OGCard);
+            };
+            linkCardPromises.push(linkCardPromise());
+        });
+        await Promise.all(linkCardPromises);
+    };
+    return transform;
+};
+export default rehypeOGCard;

package/dist/types.d.ts

@@ -0,0 +1,93 @@
+interface RehypeOGCardOptions {
+    /**
+     * Domains to exclude from conversion.
+     */
+    excludeDomains?: string[];
+    /**
+     * `decoding` attribute of the image element.
+     * @default "async"
+     */
+    decoding?: HTMLImageElement["decoding"];
+    /**
+     * `loading` attribute of the image element.
+     * @default "lazy"
+     */
+    loading?: HTMLImageElement["loading"];
+    /**
+     * Whether to shorten the displayed URL.
+     * @default true
+     */
+    shortenURL?: boolean;
+    /**
+     * Whether to open the link in a new tab.
+     * @default false
+     */
+    openInNewTab?: boolean;
+    /**
+     * Whether to enable converting the links
+     * that have the same URL and text (e.g., `[https://example.com](https://example.com)`).
+     * @default false
+     */
+    enableSameTextURLConversion?: boolean;
+    /**
+     * Whether to cache the OG data on the server.
+     * @default true
+     */
+    serverCache?: boolean;
+    /**
+     * Path to save the server cache.
+     * Specify the directory whose contents will be copied to the root.
+     * For example, for an Astro project, specify the `public` directory.
+     * @default "./public"
+     */
+    serverCachePath?: string;
+    /**
+     * Cache expiration time for server cache in milliseconds.
+     * Set to `false` to disable expiration.
+     * Expiration is calculated from the cached timestamp stored in the cache itself.
+     * @default 2592000000
+     */
+    serverCacheMaxAge?: number | false;
+    /**
+     * Whether to cache the OG metadata and images for the next build.
+     * `buildCache` option requires `serverCache` option to be enabled.
+     * @default false
+     */
+    buildCache?: boolean;
+    /**
+     * Path to save the build cache.
+     * For Astro projects, specify the `./node_modules/.astro` directory.
+     * @default "./node_modules/.cache"
+     */
+    buildCachePath?: string;
+    /**
+     * Cache expiration time for build cache in milliseconds.
+     * Set to `false` to disable expiration.
+     * Expiration is calculated from the cached timestamp stored in the cache itself.
+     * @default 2592000000
+     */
+    buildCacheMaxAge?: number | false;
+    /**
+     * User agent to use for fetching the OG metadata and images.
+     * @default "Mozilla/5.0 (compatible; rehype-og-card/2.0; +https://github.com/Robot-Inventor/rehype-og-card/; purpose=link-preview; twitterbot-compatible)"
+     */
+    crawlerUserAgent?: string;
+}
+interface OGCardData {
+    url: string;
+    title: string;
+    description?: string | undefined;
+    displayURL: string;
+    faviconURL?: string | undefined;
+    OGImageURL?: string | undefined;
+    OGImageAlt?: string | undefined;
+    OGImageWidth?: number | undefined;
+    OGImageHeight?: number | undefined;
+}
+declare const cacheIndexSchema: import("arktype/internal/variants/object.ts").ObjectType<{
+    [x: string]: {
+        createdAt: number;
+    };
+}, {}>;
+type CacheIndex = typeof cacheIndexSchema.infer;
+export { cacheIndexSchema, type RehypeOGCardOptions, type OGCardData, type CacheIndex };

package/dist/types.js

@@ -0,0 +1,7 @@
+import { type } from "arktype";
+const cacheIndexSchema = type({
+    "[string]": {
+        createdAt: "number"
+    }
+});
+export { cacheIndexSchema };

package/dist/util/cache.d.ts

@@ -0,0 +1,55 @@
+import { type CacheIndex, type OGCardData } from "../types.js";
+/**
+ * Check whether a cache entry is expired.
+ * @param cachedAtMs Cached timestamp in milliseconds.
+ * @param maxAgeMs Cache expiration time in milliseconds.
+ * @returns `true` if expired, otherwise `false`.
+ */
+declare const isCacheExpired: (cachedAtMs: number, maxAgeMs: number | false) => boolean;
+/**
+ * Get the cache index path for a directory.
+ * @param directory Cache directory path.
+ * @returns Cache index path.
+ */
+declare const getCacheIndexPath: (directory: string) => string;
+/**
+ * Read cache index.
+ * @param directory Cache directory path.
+ * @returns Cache index data.
+ */
+declare const readCacheIndex: (directory: string) => Promise<CacheIndex>;
+/**
+ * Write cache index.
+ * @param directory Cache directory path.
+ * @param index Cache index data.
+ */
+declare const writeCacheIndex: (directory: string, index: CacheIndex) => Promise<void>;
+/**
+ * Save build cache if server cache exists.
+ * @param serverCachePath Server cache path.
+ * @param buildCachePath Build cache path.
+ */
+declare const saveBuildCacheFile: (serverCachePath: string, buildCachePath: string) => Promise<void>;
+/**
+ * Restore build cache if it exists.
+ * @param buildCachePath Build cache path.
+ * @param serverCachePath Server cache path.
+ * @param maxAgeMs Cache expiration time in milliseconds.
+ */
+declare const restoreBuildCache: (buildCachePath: string, serverCachePath: string, maxAgeMs: number | false) => void;
+/**
+ * Save OG data to build cache.
+ * @param url URL of the OG data.
+ * @param OGData OG data to save.
+ * @param buildCachePath Build cache path.
+ */
+declare const saveOGDataBuildCache: (url: string, OGData: OGCardData, buildCachePath: string) => Promise<void>;
+/**
+ * Restore OG data from build cache.
+ * @param url URL of the OG data.
+ * @param buildCachePath Build cache path.
+ * @param maxAgeMs Cache expiration time in milliseconds.
+ * @returns Restored OG data. If not found, returns `null`.
+ */
+declare const restoreOGDataBuildCache: (url: string, buildCachePath: string, maxAgeMs: number | false) => Promise<OGCardData | null>;
+export { getCacheIndexPath, isCacheExpired, readCacheIndex, restoreBuildCache, restoreOGDataBuildCache, saveBuildCacheFile, saveOGDataBuildCache, writeCacheIndex };

package/dist/util/cache.js

@@ -0,0 +1,346 @@
+/* eslint-disable max-lines */
+import { cacheIndexSchema } from "../types.js";
+import { checkFileExists, generateFilename } from "./file.js";
+import fs from "fs/promises";
+import fsSync from "fs";
+import path from "path";
+import { setTimeout } from "timers/promises";
+import { type } from "arktype";
+/**
+ * Check whether a cache entry is expired.
+ * @param cachedAtMs Cached timestamp in milliseconds.
+ * @param maxAgeMs Cache expiration time in milliseconds.
+ * @returns `true` if expired, otherwise `false`.
+ */
+const isCacheExpired = (cachedAtMs, maxAgeMs) => {
+    if (maxAgeMs === false)
+        return false;
+    return Date.now() - cachedAtMs > maxAgeMs;
+};
+const CACHE_INDEX_FILENAME = "cache.json";
+const CACHE_INDEX_LOCK_FILENAME = "cache.json.lock";
+/**
+ * Get the cache index path for a directory.
+ * @param directory Cache directory path.
+ * @returns Cache index path.
+ */
+const getCacheIndexPath = (directory) => path.join(directory, CACHE_INDEX_FILENAME);
+/**
+ * Get the cache index lock path for a directory.
+ * @param directory Cache directory path.
+ * @returns Cache index lock path.
+ */
+const getCacheIndexLockPath = (directory) => path.join(directory, CACHE_INDEX_LOCK_FILENAME);
+/**
+ * Sleep synchronously for a given duration.
+ * @param ms Duration in milliseconds.
+ */
+const sleepSync = (ms) => {
+    // eslint-disable-next-line no-magic-numbers
+    const buffer = new SharedArrayBuffer(4);
+    const view = new Int32Array(buffer);
+    // eslint-disable-next-line no-magic-numbers
+    Atomics.wait(view, 0, 0, ms);
+};
+/**
+ * Acquire the cache index lock.
+ * @param directory Cache directory path.
+ * @returns Release function or `null` if locking failed.
+ */
+const acquireCacheIndexLock = async (directory) => {
+    const lockPath = getCacheIndexLockPath(directory);
+    const maxRetries = 50;
+    const delayMs = 20;
+    const firstAttempt = 0;
+    const nextAttemptIncrement = 1;
+    /**
+     * Try acquiring the cache index lock.
+     * @param attempt Current attempt count.
+     * @returns Release function or `null` if locking failed.
+     */
+    const tryAcquire = async (attempt) => {
+        try {
+            const handle = await fs.open(lockPath, "wx");
+            await handle.close();
+            return async () => {
+                await fs.rm(lockPath, { force: true });
+            };
+        }
+        catch (error) {
+            const err = error;
+            if (err.code !== "EEXIST")
+                throw error;
+            if (attempt >= maxRetries)
+                return null;
+            await setTimeout(delayMs);
+            return tryAcquire(attempt + nextAttemptIncrement);
+        }
+    };
+    return tryAcquire(firstAttempt);
+};
+/**
+ * Acquire the cache index lock synchronously.
+ * @param directory Cache directory path.
+ * @returns Release function or `null` if locking failed.
+ */
+const acquireCacheIndexLockSync = (directory) => {
+    const lockPath = getCacheIndexLockPath(directory);
+    const maxRetries = 50;
+    const delayMs = 20;
+    const firstAttempt = 0;
+    const nextAttemptIncrement = 1;
+    /**
+     * Try acquiring the cache index lock synchronously.
+     * @param attempt Current attempt count.
+     * @returns Release function or `null` if locking failed.
+     */
+    const tryAcquire = (attempt) => {
+        try {
+            const fd = fsSync.openSync(lockPath, "wx");
+            fsSync.closeSync(fd);
+            return () => {
+                fsSync.rmSync(lockPath, { force: true });
+            };
+        }
+        catch (error) {
+            const err = error;
+            if (err.code !== "EEXIST")
+                throw error;
+            if (attempt >= maxRetries)
+                return null;
+            sleepSync(delayMs);
+            return tryAcquire(attempt + nextAttemptIncrement);
+        }
+    };
+    return tryAcquire(firstAttempt);
+};
+/**
+ * Read cache index synchronously.
+ * @param directory Cache directory path.
+ * @returns Cache index data.
+ */
+const readCacheIndexSync = (directory) => {
+    const indexPath = getCacheIndexPath(directory);
+    try {
+        const raw = fsSync.readFileSync(indexPath, "utf-8");
+        const parsed = JSON.parse(raw);
+        const validated = cacheIndexSchema(parsed);
+        if (validated instanceof type.errors)
+            return {};
+        return validated;
+    }
+    catch {
+        return {};
+    }
+};
+/**
+ * Write cache index synchronously.
+ * @param directory Cache directory path.
+ * @param index Cache index data.
+ */
+const writeCacheIndexSync = (directory, index) => {
+    const indexPath = getCacheIndexPath(directory);
+    const tempPath = `${indexPath}.tmp`;
+    const releaseLock = acquireCacheIndexLockSync(directory);
+    try {
+        fsSync.writeFileSync(tempPath, JSON.stringify(index));
+        fsSync.renameSync(tempPath, indexPath);
+    }
+    finally {
+        releaseLock?.();
+    }
+};
+/**
+ * Read cache index.
+ * @param directory Cache directory path.
+ * @returns Cache index data.
+ */
+const readCacheIndex = async (directory) => {
+    const indexPath = getCacheIndexPath(directory);
+    const exists = await checkFileExists(indexPath);
+    if (!exists)
+        return {};
+    try {
+        const raw = await fs.readFile(indexPath, "utf-8");
+        const parsed = JSON.parse(raw);
+        const validated = cacheIndexSchema(parsed);
+        if (validated instanceof type.errors)
+            return {};
+        return validated;
+    }
+    catch {
+        return {};
+    }
+};
+/**
+ * Write cache index.
+ * @param directory Cache directory path.
+ * @param index Cache index data.
+ */
+const writeCacheIndex = async (directory, index) => {
+    const indexPath = getCacheIndexPath(directory);
+    const tempPath = `${indexPath}.tmp`;
+    const releaseLock = await acquireCacheIndexLock(directory);
+    try {
+        await fs.writeFile(tempPath, JSON.stringify(index));
+        await fs.rename(tempPath, indexPath);
+    }
+    finally {
+        await releaseLock?.();
+    }
+};
+/**
+ * Remove a cache file synchronously.
+ * @param directory Cache directory path.
+ * @param filename Cache filename.
+ */
+const removeCacheEntrySync = (directory, filename) => {
+    const filePath = path.join(directory, filename);
+    fsSync.rmSync(filePath, { force: true });
+};
+/**
+ * Remove expired cache files synchronously.
+ * @param directory Cache directory path.
+ * @param maxAgeMs Cache expiration time in milliseconds.
+ */
+// eslint-disable-next-line max-statements, max-lines-per-function
+const pruneExpiredCacheFilesSync = (directory, maxAgeMs) => {
+    if (maxAgeMs === false)
+        return;
+    if (!fsSync.existsSync(directory))
+        return;
+    const index = readCacheIndexSync(directory);
+    let indexUpdated = false;
+    const entries = fsSync.readdirSync(directory, { withFileTypes: true });
+    for (const entry of entries) {
+        const entryPath = path.join(directory, entry.name);
+        if (entry.isDirectory()) {
+            pruneExpiredCacheFilesSync(entryPath, maxAgeMs);
+            // eslint-disable-next-line no-continue
+            continue;
+        }
+        // eslint-disable-next-line no-continue
+        if (entry.name === CACHE_INDEX_FILENAME || entry.name === CACHE_INDEX_LOCK_FILENAME)
+            continue;
+        if (entry.name.endsWith(".json")) {
+            try {
+                const raw = fsSync.readFileSync(entryPath, "utf-8");
+                const data = JSON.parse(raw);
+                if (typeof data.cachedAt !== "number") {
+                    fsSync.rmSync(entryPath, { force: true });
+                    // eslint-disable-next-line no-continue
+                    continue;
+                }
+                if (isCacheExpired(data.cachedAt, maxAgeMs)) {
+                    fsSync.rmSync(entryPath, { force: true });
+                }
+            }
+            catch {
+                fsSync.rmSync(entryPath, { force: true });
+            }
+            // eslint-disable-next-line no-continue
+            continue;
+        }
+        const cachedAtMs = index[entry.name]?.createdAt;
+        if (typeof cachedAtMs !== "number" || isCacheExpired(cachedAtMs, maxAgeMs)) {
+            removeCacheEntrySync(directory, entry.name);
+            indexUpdated = true;
+            // eslint-disable-next-line @typescript-eslint/no-dynamic-delete
+            delete index[entry.name];
+        }
+    }
+    if (indexUpdated) {
+        writeCacheIndexSync(directory, index);
+    }
+};
+/**
+ * Save build cache if server cache exists.
+ * @param serverCachePath Server cache path.
+ * @param buildCachePath Build cache path.
+ */
+// eslint-disable-next-line max-statements
+const saveBuildCacheFile = async (serverCachePath, buildCachePath) => {
+    const serverCacheExists = await checkFileExists(serverCachePath);
+    const buildCacheExists = await checkFileExists(buildCachePath);
+    if (serverCacheExists && !buildCacheExists) {
+        await fs.copyFile(serverCachePath, buildCachePath);
+    }
+    const buildCacheExistsAfter = await checkFileExists(buildCachePath);
+    if (!buildCacheExistsAfter)
+        return;
+    const serverDirectory = path.dirname(serverCachePath);
+    const buildDirectory = path.dirname(buildCachePath);
+    const filename = path.basename(buildCachePath);
+    const serverIndex = readCacheIndexSync(serverDirectory);
+    const cachedAt = typeof serverIndex[filename]?.createdAt === "number" ? serverIndex[filename].createdAt : Date.now();
+    const buildIndex = readCacheIndexSync(buildDirectory);
+    buildIndex[filename] = { createdAt: cachedAt };
+    writeCacheIndexSync(buildDirectory, buildIndex);
+};
+/**
+ * Restore build cache if it exists.
+ * @param buildCachePath Build cache path.
+ * @param serverCachePath Server cache path.
+ * @param maxAgeMs Cache expiration time in milliseconds.
+ */
+const restoreBuildCache = (buildCachePath, serverCachePath, maxAgeMs) => {
+    if (!fsSync.existsSync(buildCachePath))
+        return;
+    pruneExpiredCacheFilesSync(buildCachePath, maxAgeMs);
+    if (!fsSync.existsSync(serverCachePath)) {
+        fsSync.mkdirSync(serverCachePath, { recursive: true });
+    }
+    fsSync.cpSync(buildCachePath, serverCachePath, { recursive: true });
+};
+/**
+ * Save OG data to build cache.
+ * @param url URL of the OG data.
+ * @param OGData OG data to save.
+ * @param buildCachePath Build cache path.
+ */
+const saveOGDataBuildCache = async (url, OGData, buildCachePath) => {
+    const filename = generateFilename(url, false);
+    const savePath = `${path.join(buildCachePath, filename)}.json`;
+    const cacheDirectoryExists = await checkFileExists(buildCachePath);
+    if (!cacheDirectoryExists) {
+        await fs.mkdir(buildCachePath, { recursive: true });
+    }
+    const payload = { ...OGData, cachedAt: Date.now() };
+    await fs.writeFile(savePath, JSON.stringify(payload));
+};
+/**
+ * Restore OG data from build cache.
+ * @param url URL of the OG data.
+ * @param buildCachePath Build cache path.
+ * @param maxAgeMs Cache expiration time in milliseconds.
+ * @returns Restored OG data. If not found, returns `null`.
+ */
+// eslint-disable-next-line max-statements
+const restoreOGDataBuildCache = async (url, buildCachePath, maxAgeMs) => {
+    const filename = generateFilename(url, false);
+    const savePath = `${path.join(buildCachePath, filename)}.json`;
+    try {
+        const data = await fs.readFile(savePath, "utf-8");
+        const parsed = JSON.parse(data);
+        if (typeof parsed.cachedAt !== "number") {
+            if (maxAgeMs === false) {
+                // eslint-disable-next-line @typescript-eslint/no-unused-vars
+                const { cachedAt: __, ...rest } = parsed;
+                return rest;
+            }
+            await fs.rm(savePath, { force: true });
+            return null;
+        }
+        if (isCacheExpired(parsed.cachedAt, maxAgeMs)) {
+            await fs.rm(savePath, { force: true });
+            return null;
+        }
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
+        const { cachedAt: __, ...rest } = parsed;
+        return rest;
+    }
+    catch {
+        return null;
+    }
+};
+export { getCacheIndexPath, isCacheExpired, readCacheIndex, restoreBuildCache, restoreOGDataBuildCache, saveBuildCacheFile, saveOGDataBuildCache, writeCacheIndex };

package/dist/util/file.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Check if the file exists.
+ * @param filePath Path to check.
+ * @returns `true` if the file exists, `false` otherwise.
+ */
+declare const checkFileExists: (filePath: string) => Promise<boolean>;
+/**
+ * Check if the file exists.
+ * @param filePath Path to check.
+ * @returns `true` if the file exists, `false` otherwise.
+ */
+declare const checkFileExistsSync: (filePath: string) => boolean;
+/**
+ * Create directory.
+ * @param dir Directory path.
+ */
+declare const createDirectorySync: (dir: string) => void;
+/**
+ * Copy directory from source to destination.
+ * @param source Source directory.
+ * @param destination Destination directory.
+ */
+declare const copyDirectory: (source: string, destination: string) => void;
+/**
+ * Generate filename from URL.
+ * @param url URL to generate filename.
+ * @param extension Include extension in the filename.
+ * @returns Generated filename.
+ */
+declare const generateFilename: (url: string, extension?: boolean) => string;
+export { checkFileExists, checkFileExistsSync, createDirectorySync, copyDirectory, generateFilename };

package/dist/util/file.js

@@ -0,0 +1,78 @@
+import { createHash } from "crypto";
+import fs from "fs";
+import path from "path";
+/**
+ * Check if the file exists.
+ * @param filePath Path to check.
+ * @returns `true` if the file exists, `false` otherwise.
+ */
+const checkFileExists = async (filePath) => {
+    try {
+        await fs.promises.access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+/**
+ * Check if the file exists.
+ * @param filePath Path to check.
+ * @returns `true` if the file exists, `false` otherwise.
+ */
+const checkFileExistsSync = (filePath) => {
+    let result = false;
+    fs.access(filePath, (error) => {
+        result = !error;
+    });
+    return result;
+};
+/**
+ * Create directory.
+ * @param dir Directory path.
+ */
+const createDirectorySync = (dir) => {
+    fs.mkdir(dir, { recursive: true }, (error) => {
+        if (error) {
+            // eslint-disable-next-line no-console
+            console.error("[rehype-og-card] Failed to copy files: ", error);
+        }
+    });
+};
+/**
+ * Copy directory from source to destination.
+ * @param source Source directory.
+ * @param destination Destination directory.
+ */
+const copyDirectory = (source, destination) => {
+    const sourceExists = checkFileExistsSync(source);
+    if (!sourceExists)
+        return;
+    const destinationExists = checkFileExistsSync(destination);
+    if (!destinationExists) {
+        createDirectorySync(destination);
+    }
+    fs.cp(source, destination, { recursive: true }, (error) => {
+        if (error) {
+            // eslint-disable-next-line no-console
+            console.error("[rehype-og-card] Failed to copy files: ", error);
+        }
+    });
+};
+/**
+ * Generate filename from URL.
+ * @param url URL to generate filename.
+ * @param extension Include extension in the filename.
+ * @returns Generated filename.
+ */
+const generateFilename = (url, extension = true) => {
+    const hash = createHash("sha256").update(url).digest("hex");
+    const possibleExtension = path.extname(new URL(url).pathname).toLowerCase();
+    const allowedExtensions = [".png", ".jpg", ".jpeg", ".webp", ".gif", ".avif", ".svg"];
+    const extensionString = allowedExtensions.includes(possibleExtension)
+        ? possibleExtension
+        : "";
+    const filename = extension ? hash + extensionString : hash;
+    return filename;
+};
+export { checkFileExists, checkFileExistsSync, createDirectorySync, copyDirectory, generateFilename };

package/dist/util/hast.d.ts

@@ -0,0 +1,38 @@
+import type { Element, ElementContent, Text } from "hast";
+import type { OGCardData, RehypeOGCardOptions } from "../types.js";
+interface AnchorElement extends Element {
+    tagName: "a";
+    properties: {
+        href: string;
+    };
+}
+/**
+ * Check if the node is a text node.
+ * @param node Node to check.
+ * @returns `true` if the node is a text node, `false` otherwise.
+ */
+declare const isTextNode: (node: ElementContent) => node is Text;
+/**
+ * Check if the node is an anchor element.
+ * @param node Node to check.
+ * @returns `true` if the node is an anchor element, `false` otherwise.
+ */
+declare const isAnchorElement: (node: unknown) => node is AnchorElement;
+/**
+ * Convert text node to anchor element. **This function does not check if the text is a valid URL.**
+ * @param text Text node to convert.
+ * @returns Anchor element.
+ */
+declare const convertTextToAnchorElement: (text: Text) => AnchorElement;
+/**
+ * Create OG card element from given data.
+ * @param data Data to create OG card.
+ * @param options Options to create OG card.
+ * @returns OG card element.
+ */
+declare const createOGCard: (data: OGCardData, options: Required<{
+    loading: RehypeOGCardOptions["loading"];
+    decoding: RehypeOGCardOptions["decoding"];
+    openInNewTab: RehypeOGCardOptions["openInNewTab"];
+}>) => Element;
+export { type AnchorElement, isTextNode, isAnchorElement, convertTextToAnchorElement, createOGCard };

package/dist/util/hast.js

@@ -0,0 +1,73 @@
+import { h } from "hastscript";
+import { isElement } from "hast-util-is-element";
+/**
+ * Check if the node is a text node.
+ * @param node Node to check.
+ * @returns `true` if the node is a text node, `false` otherwise.
+ */
+const isTextNode = (node) => Boolean(node) && typeof node === "object" && "type" in node && node.type === "text";
+/**
+ * Check if the node is an anchor element.
+ * @param node Node to check.
+ * @returns `true` if the node is an anchor element, `false` otherwise.
+ */
+const isAnchorElement = (node) => Boolean(node) && isElement(node, "a") && "href" in node.properties && typeof node.properties["href"] === "string";
+/**
+ * Convert text node to anchor element. **This function does not check if the text is a valid URL.**
+ * @param text Text node to convert.
+ * @returns Anchor element.
+ */
+const convertTextToAnchorElement = (text) => ({
+    children: [text],
+    properties: {
+        href: text.value.trim()
+    },
+    tagName: "a",
+    type: "element"
+});
+/**
+ * Create OG card element from given data.
+ * @param data Data to create OG card.
+ * @param options Options to create OG card.
+ * @returns OG card element.
+ */
+const createOGCard = (data, options) => {
+    const openInNewTab = {
+        rel: "noopener noreferrer",
+        target: "_blank"
+    };
+    const card = h("div.og-card-container", [
+        h("a", { href: data.url, ...(options.openInNewTab ? openInNewTab : {}) }, [
+            h("div.og-card-info", [
+                h("div.og-card-title", data.title),
+                data.description ? h("div.og-card-description", data.description) : null,
+                h("div.og-card-url-container", [
+                    h("img.og-card-favicon", {
+                        alt: "favicon",
+                        decoding: options.decoding,
+                        height: 16,
+                        loading: options.loading,
+                        src: data.faviconURL,
+                        width: 16
+                    }),
+                    h("span.og-card-url", data.displayURL)
+                ])
+            ]),
+            data.OGImageURL
+                ? h("div.og-card-image-container", [
+                    h("img.og-card-image", {
+                        // eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing
+                        alt: data.OGImageAlt || data.OGImageURL,
+                        decoding: options.decoding,
+                        height: data.OGImageHeight,
+                        loading: options.loading,
+                        src: data.OGImageURL,
+                        width: data.OGImageWidth
+                    })
+                ])
+                : null
+        ])
+    ]);
+    return card;
+};
+export { isTextNode, isAnchorElement, convertTextToAnchorElement, createOGCard };

package/dist/util/network.d.ts

@@ -0,0 +1,40 @@
+import type { OGCardData } from "../types.js";
+/**
+ * Check if the URL is valid.
+ * @param url URL to check.
+ * @returns `true` if the URL is valid, `false` otherwise.
+ */
+declare const isValidURL: (url: string) => boolean;
+/**
+ * Get OG card data from given URL.
+ * @param url URL to get OG card data.
+ * @param userAgent User agent to use for fetching.
+ * @returns OG card data.
+ */
+declare const getOGData: (url: string, userAgent: string) => Promise<OGCardData | null>;
+interface DownloadImageOptions {
+    /**
+     * URL to download image.
+     */
+    url: string;
+    /**
+     * Directory to save the downloaded image.
+     */
+    directory: string;
+    /**
+     * User agent to use for fetching the image.
+     */
+    userAgent: string;
+    /**
+     * Cache expiration time in milliseconds.
+     * Set to `false` to disable expiration.
+     */
+    cacheMaxAge: number | false;
+}
+/**
+ * Download image from given URL. If the image already exists, return the filename.
+ * @param options Options to download image.
+ * @returns Filename of the downloaded image.
+ */
+declare const downloadImage: (options: DownloadImageOptions) => Promise<string | null>;
+export { isValidURL, getOGData, downloadImage };

package/dist/util/network.js

@@ -0,0 +1,129 @@
+import { checkFileExists, generateFilename } from "./file.js";
+import { isCacheExpired, readCacheIndex, writeCacheIndex } from "./cache.js";
+import fetch from "node-fetch";
+import fs from "fs/promises";
+import path from "path";
+import scraper from "open-graph-scraper";
+/**
+ * Check if the URL is valid.
+ * @param url URL to check.
+ * @returns `true` if the URL is valid, `false` otherwise.
+ */
+const isValidURL = (url) => {
+    const ALLOWED_PROTOCOLS = ["http:", "https:"];
+    const parsedUrl = URL.parse(url);
+    return Boolean(parsedUrl && ALLOWED_PROTOCOLS.includes(parsedUrl.protocol));
+};
+/**
+ * Resolve an absolute URL from a raw URL and a base URL.
+ * @param rawURL Raw URL to resolve.
+ * @param baseURL Base URL to resolve against.
+ * @returns Resolved absolute URL or `undefined` if the raw URL is invalid.
+ */
+const resolveAbsoluteURL = (rawURL, baseURL) => {
+    // eslint-disable-next-line no-undefined
+    if (!rawURL)
+        return undefined;
+    const parsedUrl = URL.parse(rawURL, baseURL);
+    // eslint-disable-next-line no-undefined
+    return parsedUrl ? parsedUrl.href : undefined;
+};
+/**
+ * Get OG card data from given URL.
+ * @param url URL to get OG card data.
+ * @param userAgent User agent to use for fetching.
+ * @returns OG card data.
+ */
+const getOGData = async (url, userAgent) => {
+    try {
+        const { result } = await scraper({
+            fetchOptions: {
+                headers: {
+                    "user-agent": userAgent
+                }
+            },
+            url
+        });
+        const OGImage = result.ogImage ? result.ogImage[0] : null;
+        const OGImageURL = resolveAbsoluteURL(OGImage?.url, url);
+        const resolvedFaviconURL = result.favicon ? resolveAbsoluteURL(result.favicon, url) : null;
+        const faviconURL = resolvedFaviconURL ?? `https://www.google.com/s2/favicons?domain=${new URL(url).hostname}`;
+        return {
+            OGImageAlt: OGImage?.alt,
+            OGImageHeight: OGImage?.height,
+            OGImageURL,
+            OGImageWidth: OGImage?.width,
+            description: result.ogDescription,
+            displayURL: url,
+            faviconURL,
+            // eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing
+            title: result.ogTitle || url,
+            url
+        };
+    }
+    catch (error) {
+        // eslint-disable-next-line no-console
+        console.error("[rehype-og-card] Error fetching OG data:", error);
+        return null;
+    }
+};
+/**
+ * Download image from given URL. If the image already exists, return the filename.
+ * @param options Options to download image.
+ * @returns Filename of the downloaded image.
+ */
+// eslint-disable-next-line max-statements, max-lines-per-function
+const downloadImage = async (options) => {
+    if (!isValidURL(options.url)) {
+        // eslint-disable-next-line no-console
+        console.error("[rehype-og-card] Invalid thumbnail URL:", options.url);
+        return null;
+    }
+    try {
+        const filename = generateFilename(options.url);
+        const savePath = path.posix.join(options.directory, filename);
+        // If the file already exists, return the filename.
+        const fileExists = await checkFileExists(savePath);
+        if (fileExists) {
+            if (options.cacheMaxAge === false)
+                return filename;
+            const index = await readCacheIndex(options.directory);
+            const entry = index[filename];
+            const cachedAt = entry?.createdAt;
+            const maxAge = options.cacheMaxAge;
+            if (typeof cachedAt === "number" && !isCacheExpired(cachedAt, maxAge))
+                return filename;
+            if (typeof entry !== "undefined") {
+                // eslint-disable-next-line @typescript-eslint/no-dynamic-delete
+                delete index[filename];
+                await writeCacheIndex(options.directory, index);
+            }
+            await fs.rm(savePath, { force: true });
+        }
+        const response = await fetch(options.url, {
+            headers: {
+                "user-agent": options.userAgent
+            },
+            // eslint-disable-next-line no-magic-numbers
+            signal: AbortSignal.timeout(10 * 1000)
+        });
+        const arrayBuffer = await response.arrayBuffer();
+        const buffer = Buffer.from(arrayBuffer);
+        const saveDirectoryExists = await checkFileExists(options.directory);
+        if (!saveDirectoryExists) {
+            await fs.mkdir(options.directory, { recursive: true });
+        }
+        await fs.writeFile(savePath, buffer);
+        const cachedAt = Date.now();
+        const index = await readCacheIndex(options.directory);
+        index[filename] = { createdAt: cachedAt };
+        await writeCacheIndex(options.directory, index);
+        return filename;
+    }
+    catch (error) {
+        // eslint-disable-next-line no-console
+        console.error("[rehype-og-card] Error downloading image:", error);
+        return null;
+    }
+};
+export { isValidURL, getOGData, downloadImage };

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "rehype-og-card",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "description": "Rehype plugin to convert text links to link cards",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [
-    "./dist"
+    "dist"
   ],
   "type": "module",
   "publishConfig": {