metanova 0.1.0

package/examples/behance.mjs

@@ -0,0 +1,23 @@
+import { createPreviewCard, parseMetadata } from "metanova";
+
+const html = `
+  <script id="__NEXT_DATA__" type="application/json">
+    {
+      "props": {
+        "pageProps": {
+          "project": {
+            "projectTitle": "Identity system for MetaNova",
+            "description": "A Behance-style project page powered by Next.js data.",
+            "owners": [{ "name": "Creative Lab" }],
+            "publishedTime": "2026-06-04T11:00:00Z",
+            "coverImage": { "url": "https://mir-s3-cdn-cf.behance.net/project-cover.jpg", "width": 1400, "height": 1000 }
+          }
+        }
+      }
+    }
+  </script>
+`;
+
+const metadata = parseMetadata(html, "https://www.behance.net/gallery/123456789/metanova");
+
+console.log(createPreviewCard(metadata));

package/examples/commonjs.cjs

@@ -0,0 +1,12 @@
+const { parseMetadata } = require("metanova");
+
+const metadata = parseMetadata(
+  `<title>CommonJS example</title><meta name="description" content="Loaded with require.">`,
+  "https://example.com/commonjs"
+);
+
+console.log({
+  title: metadata.title,
+  type: metadata.type,
+  confidence: metadata.confidence
+});

package/examples/custom-adapter.mjs

@@ -0,0 +1,41 @@
+import { parseMetadata } from "metanova";
+
+const docsAdapter = {
+  name: "docsAdapter",
+  detect(url) {
+    return url.hostname === "docs.example.com";
+  },
+  extract({ raw }) {
+    return {
+      source: "docsAdapter",
+      title: raw.openGraph.title,
+      description: raw.openGraph.description,
+      images: raw.openGraph.images,
+      platform: "Example Docs"
+    };
+  },
+  normalize(rawData) {
+    return {
+      ...rawData,
+      source: "docsAdapter",
+      type: "article",
+      siteName: rawData.platform
+    };
+  }
+};
+
+const metadata = parseMetadata(`
+  <meta property="og:title" content="Adapter example">
+  <meta property="og:description" content="Custom site-specific behavior.">
+  <meta property="og:image" content="/adapter.jpg">
+  <meta property="og:image:width" content="1200">
+  <meta property="og:image:height" content="630">
+`, "https://docs.example.com/guides/adapter", {
+  adapters: [docsAdapter]
+});
+
+console.log({
+  type: metadata.type,
+  siteName: metadata.siteName,
+  title: metadata.title
+});

package/examples/custom-plugin.mjs

@@ -0,0 +1,26 @@
+import { parseMetadata } from "metanova";
+
+const docsPlugin = {
+  name: "docs-plugin",
+  setup(api) {
+    api.addExtractor("docs-meta", ({ $ }) => ({
+      source: "docs-meta",
+      title: $("meta[name='doc:title']").attr("content"),
+      siteName: "Docs"
+    }));
+
+    api.addImageScorer((image) => (image.url.includes("/hero/") ? 12 : 0));
+  }
+};
+
+const metadata = parseMetadata(
+  `<meta name="doc:title" content="Plugin powered docs"><img src="/hero/docs.jpg" width="1200" height="630">`,
+  "https://docs.example.com/guide",
+  { plugins: [docsPlugin] }
+);
+
+console.log({
+  title: metadata.title,
+  siteName: metadata.siteName,
+  bestImage: metadata.bestImage
+});

package/examples/diagnostics.mjs

@@ -0,0 +1,17 @@
+import { parseMetadata } from "metanova";
+
+const metadata = parseMetadata(`
+  <meta property="og:title" content="Diagnostics example">
+  <meta property="og:description" content="Inspect trace, confidence, completeness, and image scoring.">
+  <meta property="og:image" content="/social-preview.jpg">
+  <meta property="og:image:width" content="1200">
+  <meta property="og:image:height" content="630">
+`, "https://example.com/post");
+
+console.log({
+  confidence: metadata.confidence,
+  completeness: metadata.completeness,
+  bestImage: metadata.bestImage,
+  selectedImageReason: metadata.diagnostics.selectedImageReason,
+  trace: metadata.diagnostics.trace
+});

package/examples/live-fetch.mjs

@@ -0,0 +1,21 @@
+import { createPreviewCard, fetchMetadata } from "metanova";
+
+const url = process.argv[2];
+
+if (!url) {
+  console.error("Usage: node examples/live-fetch.mjs <url>");
+  process.exitCode = 1;
+} else {
+  const metadata = await fetchMetadata(url, {
+    timeoutMs: 15000,
+    maxBytes: 4_000_000
+  });
+
+  console.log(createPreviewCard(metadata));
+  console.log({
+    confidence: metadata.confidence,
+    completeness: metadata.completeness,
+    reliability: metadata.reliability,
+    diagnostics: metadata.diagnostics
+  });
+}

package/examples/parse-html.mjs

@@ -0,0 +1,15 @@
+import { parseMetadata } from "metanova";
+
+const html = `
+  <html>
+    <head>
+      <title>Parsed HTML</title>
+      <meta name="description" content="Parse already-downloaded HTML.">
+      <img src="/inline.jpg" width="800" height="450">
+    </head>
+  </html>
+`;
+
+const metadata = parseMetadata(html, "https://example.com/articles/parsed-html");
+
+console.log(metadata);

package/examples/pinterest.mjs

@@ -0,0 +1,22 @@
+import { createPreviewCard, parseMetadata } from "metanova";
+
+const html = `
+  <meta property="og:site_name" content="Pinterest">
+  <script id="__PWS_DATA__" type="application/json">
+    {
+      "props": {
+        "pin": {
+          "pinTitle": "A clean product moodboard",
+          "description": "Pinterest-style embedded pin payload.",
+          "pinner": { "name": "Design Studio" },
+          "createdAt": "2026-06-04T10:00:00Z",
+          "images": [{ "url": "https://i.pinimg.com/originals/pin-cover.jpg", "width": 1200, "height": 1800 }]
+        }
+      }
+    }
+  </script>
+`;
+
+const metadata = parseMetadata(html, "https://www.pinterest.com/pin/123456789/");
+
+console.log(createPreviewCard(metadata));

package/examples/preview-card.mjs

@@ -0,0 +1,11 @@
+import { createPreviewCard, parseMetadata } from "metanova";
+
+const metadata = parseMetadata(`
+  <meta property="og:title" content="Preview Card">
+  <meta property="og:description" content="Small JSON for bots and apps.">
+  <meta property="og:image" content="/preview-card.jpg">
+  <meta property="og:image:width" content="1200">
+  <meta property="og:image:height" content="630">
+`, "https://example.com/preview-card");
+
+console.log(createPreviewCard(metadata));

package/examples/quick-start.mjs

@@ -0,0 +1,24 @@
+import { createPreviewCard, fetchMetadata } from "metanova";
+
+const html = `
+  <html>
+    <head>
+      <meta property="og:title" content="MetaNova Quick Start">
+      <meta property="og:description" content="A fast metadata extraction example.">
+      <meta property="og:image" content="http://127.0.0.1/cover.jpg">
+      <meta property="og:image:width" content="1200">
+      <meta property="og:image:height" content="630">
+      <link rel="canonical" href="http://127.0.0.1/posts/quick-start">
+    </head>
+  </html>
+`;
+
+const metadata = await fetchMetadata("http://127.0.0.1/posts/quick-start", {
+  allowLocalhost: true,
+  fetch: async () => new Response(html, {
+    status: 200,
+    headers: { "content-type": "text/html; charset=utf-8" }
+  })
+});
+
+console.log(createPreviewCard(metadata));

package/examples/reddit.mjs

@@ -0,0 +1,23 @@
+import { createPreviewCard, parseMetadata } from "metanova";
+
+const html = `
+  <title>Fallback Reddit title</title>
+  <meta property="og:site_name" content="Reddit">
+  <script>
+    window.__INITIAL_STATE__ = {
+      "post": {
+        "title": "MetaNova real world extraction",
+        "description": "A Reddit-style post with useful embedded data.",
+        "author": { "name": "u/metanova" },
+        "createdAt": "2026-06-04T09:00:00Z",
+        "previewImage": "https://preview.redd.it/metanova-card.jpg",
+        "media": { "videoUrl": "https://v.redd.it/metanova/DASH_720.mp4" }
+      }
+    };
+  </script>
+`;
+
+const metadata = parseMetadata(html, "https://www.reddit.com/r/typescript/comments/abc123/metanova/");
+
+console.log(createPreviewCard(metadata));
+console.log(metadata.diagnostics.trace);

package/examples/social-links.mjs

@@ -0,0 +1,28 @@
+import { parseMetadata } from "metanova";
+
+const html = `
+  <meta property="og:title" content="Platform post">
+  <meta property="og:description" content="A public social or media page.">
+  <meta property="og:image" content="/cover.jpg">
+  <meta property="og:image:width" content="1200">
+  <meta property="og:image:height" content="630">
+`;
+
+const urls = [
+  "https://www.reddit.com/r/typescript/comments/abc123/metanova/",
+  "https://www.pinterest.com/pin/123456789/",
+  "https://www.behance.net/gallery/123456789/project",
+  "https://youtu.be/dQw4w9WgXcQ",
+  "https://x.com/example/status/1234567890",
+  "https://www.instagram.com/p/ABC123/"
+];
+
+for (const url of urls) {
+  const metadata = parseMetadata(html, url);
+  console.log({
+    url,
+    type: metadata.type,
+    siteName: metadata.siteName,
+    bestImage: metadata.bestImage
+  });
+}

package/examples/social-preview.mjs

@@ -0,0 +1,21 @@
+import { createPreviewCard, fetchMetadata } from "metanova";
+
+const url = process.argv[2];
+
+if (!url) {
+  console.error("Usage: node examples/social-preview.mjs <social-url>");
+  process.exitCode = 1;
+} else {
+  const metadata = await fetchMetadata(url, {
+    timeoutMs: 15000,
+    maxBytes: 4_000_000
+  });
+
+  console.log(createPreviewCard(metadata));
+  console.log({
+    sources: metadata.sources,
+    adapter: metadata.diagnostics.adapter,
+    trace: metadata.diagnostics.trace,
+    selectedImageReason: metadata.diagnostics.selectedImageReason
+  });
+}

package/examples/youtube-playlist.mjs

@@ -0,0 +1,19 @@
+import { fetchMetadata } from "metanova";
+
+const url = process.argv[2];
+
+if (!url) {
+  console.error("Usage: node examples/youtube-playlist.mjs <youtube-playlist-or-watch-url>");
+  process.exitCode = 1;
+} else {
+  const metadata = await fetchMetadata(url, {
+    timeoutMs: 15000,
+    maxBytes: 5_000_000
+  });
+
+  console.log({
+    type: metadata.type,
+    playlist: metadata.playlist,
+    diagnostics: metadata.diagnostics
+  });
+}

package/examples/youtube-video.mjs

@@ -0,0 +1,22 @@
+import { fetchMetadata } from "metanova";
+
+const url = process.argv[2];
+
+if (!url) {
+  console.error("Usage: node examples/youtube-video.mjs <youtube-video-url>");
+  process.exitCode = 1;
+} else {
+  const metadata = await fetchMetadata(url, {
+    timeoutMs: 15000,
+    maxBytes: 5_000_000
+  });
+
+  console.log({
+    title: metadata.title,
+    channel: metadata.video?.channel ?? metadata.author,
+    video: metadata.video,
+    bestImage: metadata.bestImage,
+    confidence: metadata.confidence,
+    diagnostics: metadata.diagnostics
+  });
+}

package/examples/youtube.mjs

@@ -0,0 +1,22 @@
+import { createPreviewCard, parseMetadata } from "metanova";
+
+const html = `
+  <meta property="og:site_name" content="YouTube">
+  <script>
+    window.__INITIAL_STATE__ = {
+      "videoDetails": {
+        "title": "Building MetaNova",
+        "description": "A YouTube-style payload without relying only on OG tags.",
+        "ownerChannelName": "MetaNova Labs",
+        "uploadDate": "2026-06-04T12:00:00Z",
+        "contentUrl": "https://www.youtube.com/embed/dQw4w9WgXcQ",
+        "thumbnail": { "url": "https://i.ytimg.com/vi/dQw4w9WgXcQ/maxresdefault.jpg", "width": 1280, "height": 720 }
+      }
+    };
+  </script>
+`;
+
+const metadata = parseMetadata(html, "https://youtu.be/dQw4w9WgXcQ");
+
+console.log(createPreviewCard(metadata));
+console.log(metadata.videos);

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "metanova",
+  "version": "0.1.0",
+  "description": "A modular TypeScript metadata extraction and normalization library for web pages and public URLs.",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "USAGE_GUIDE.md",
+    "LICENSE",
+    "examples"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --sourcemap --clean",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "lint": "eslint \"src/**/*.ts\" \"test/**/*.ts\" \"examples/**/*.mjs\" \"examples/**/*.cjs\""
+  },
+  "keywords": [
+    "metadata",
+    "open-graph",
+    "twitter-cards",
+    "json-ld",
+    "schema.org",
+    "oembed",
+    "link-preview",
+    "scraping",
+    "preview-card",
+    "social-media",
+    "nextjs",
+    "metadata-extraction",
+    "ssrf-protection"
+  ],
+  "author": "MetaNova Contributors",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/xredspinel-coder/MetaNova.git"
+  },
+  "homepage": "https://github.com/xredspinel-coder/MetaNova#readme",
+  "bugs": {
+    "url": "https://github.com/xredspinel-coder/MetaNova/issues"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.18"
+  },
+  "dependencies": {
+    "cheerio": "^1.1.2"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.1",
+    "@types/node": "^24.10.1",
+    "eslint": "^9.39.1",
+    "tsup": "^8.5.0",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.46.4",
+    "vitest": "^4.0.8"
+  }
+}