🔮 ogie

> Lightweight, production-ready OpenGraph and metadata extraction for Node.js


A comprehensive metadata extraction library that pulls OpenGraph, Twitter Cards, JSON-LD, Dublin Core, and more from any webpage. Built with TypeScript, secure by default, and optimized for production use.

✨ Features

- 🎯 Comprehensive Extraction — OpenGraph, Twitter Cards, JSON-LD, Dublin Core, Article, Video, Music, Book, Profile, App Links, oEmbed, RSS/Atom Feeds
- 🚀 High Performance — LRU caching with TTL, bulk extraction with smart rate limiting
- 🔒 Secure by Default — SSRF protection, private IP blocking, URL validation
- 📦 Minimal Dependencies — Just 4 production deps (cheerio, quick-lru, bottleneck, iconv-lite)
- 🎨 TypeScript First — Full type safety with exported interfaces and type guards
- ⚡ Smart Fallbacks — Automatically fills missing OG data from Twitter Cards and meta tags
- 🌐 Charset Detection — Auto-detect and convert non-UTF-8 pages
- 📊 Bulk Processing — Process hundreds of URLs with per-domain rate limiting
- 🔤 Case-Insensitive Parsing — Handles meta tags regardless of attribute casing

🤖 AI Agent Skill

This package is available as an Agent Skill for AI coding assistants like Claude Code, Cursor, Copilot, and more.

``bash
npx skills add dobroslavradosavljevic/ogie
`

Once installed, your AI agent will know how to extract OpenGraph, Twitter Cards, and metadata from URLs or HTML.

📥 Installation

`bash


npm

npm install ogie

yarn

yarn add ogie

pnpm

pnpm add ogie

bun

bun add ogie
`

🚀 Quick Start

`typescript
import { extract } from "ogie";

// Extract metadata from a URL
const result = await extract("https://github.com");

if (result.success) {
console.log(result.data.og.title); // "GitHub: Let's build from here"
console.log(result.data.og.description); // "GitHub is where..."
console.log(result.data.og.images[0]?.url); // "https://github.githubassets.com/..."
} else {
console.error(result.error.code); // "FETCH_ERROR", "INVALID_URL", etc.
}
`

📖 API Reference

$3

Extract metadata from a URL by fetching and parsing the page.

`typescript
import { extract } from "ogie";

const result = await extract("https://example.com");

// With options
const result = await extract("https://example.com", {
timeout: 10000, // Request timeout (ms)
maxRedirects: 5, // Max redirects to follow
userAgent: "MyBot/1.0", // Custom User-Agent
fetchOEmbed: true, // Also fetch oEmbed endpoint
convertCharset: true, // Auto-detect and convert charset
});

if (result.success) {
console.log(result.data.og.title);
console.log(result.data.twitter.card);
console.log(result.data.basic.favicon);
}
`

Returns: Promise

---

$3

Extract metadata from an HTML string without making network requests.

`typescript
import { extractFromHtml } from "ogie";

const html =








;

const result = extractFromHtml(html, {
baseUrl: "https://example.com", // Required for resolving relative URLs
});

if (result.success) {
console.log(result.data.og.title); // "My Page"
console.log(result.data.og.images[0]?.url); // "https://example.com/images/hero.jpg"
}
`

Returns: ExtractResult

---

$3

Extract metadata from multiple URLs with built-in rate limiting and concurrency control.

`typescript
import { extractBulk } from "ogie";

const urls = [
"https://github.com",
"https://twitter.com",
"https://youtube.com",
"https://medium.com",
];

const result = await extractBulk(urls, {
concurrency: 10, // Max parallel requests globally
concurrencyPerDomain: 3, // Max parallel per domain
minDelayPerDomain: 200, // Min ms between same-domain requests
requestsPerMinute: 600, // Global rate limit
timeout: 30000, // Timeout per request
continueOnError: true, // Don't stop on failures
onProgress: (progress) => {
console.log(${progress.completed}/${progress.total} done);
console.log(✅ ${progress.succeeded} | ❌ ${progress.failed});
},
});

// Access results
console.log(Total time: ${result.totalDurationMs}ms);
console.log(Succeeded: ${result.stats.succeeded});
console.log(Failed: ${result.stats.failed});

// Iterate results (maintains input order)
for (const item of result.results) {
console.log(${item.url}: ${item.durationMs}ms);
if (item.result.success) {
console.log( Title: ${item.result.data.og.title});
} else {
console.log( Error: ${item.result.error.code});
}
}
`

Returns: Promise

---

$3

Create an LRU cache instance for storing extraction results.

`typescript
import { extract, createCache } from "ogie";

const cache = createCache({
maxSize: 100, // Max cached items (default: 100)
ttl: 300_000, // Time-to-live in ms (default: 5 minutes)
onEviction: (key, value) => {
console.log(Evicted: ${key});
},
});

// First call fetches from network
const result1 = await extract("https://github.com", { cache });

// Second call returns cached result instantly
const result2 = await extract("https://github.com", { cache });

// Force fresh fetch (result still gets cached)
const result3 = await extract("https://github.com", {
cache,
bypassCache: true,
});

// Cache utilities
console.log(Cache size: ${cache.size});
cache.clear(); // Clear all entries
`

Returns: MetadataCache (QuickLRU instance)

---

$3

Generate a cache key for a URL and options combination.

`typescript
import { generateCacheKey } from "ogie";

const key1 = generateCacheKey("https://example.com");
const key2 = generateCacheKey("https://example.com/"); // Same key (normalized)

// Different options produce different keys
const key3 = generateCacheKey("https://example.com", { fetchOEmbed: true });
console.log(key1 === key3); // false
`

Returns: string

📊 Extracted Metadata

Ogie extracts metadata from 13 different sources:

$3

Core OpenGraph metadata for any page type.

`typescript
{
title: "Page Title",
description: "Page description",
type: "website", // website, article, video.movie, music.song, book, profile, etc.
url: "https://example.com",
siteName: "Example",
locale: "en_US",
localeAlternate: ["es_ES", "fr_FR"],
determiner: "the",
images: [
{ url: "https://...", width: 1200, height: 630, alt: "...", secureUrl: "https://...", type: "image/jpeg" }
],
videos: [
{ url: "https://...", width: 1280, height: 720, type: "video/mp4", secureUrl: "https://..." }
],
audio: [
{ url: "https://...", type: "audio/mpeg", secureUrl: "https://..." }
],
}
`

$3

Twitter/X card metadata with full support for all card types.

`typescript
{
card: "summary_large_image", // summary, summary_large_image, app, player
site: "@github",
siteId: "13334762", // Numeric user ID
creator: "@username",
creatorId: "12345678", // Numeric user ID
title: "Card Title",
description: "Card description",
image: { url: "https://...", alt: "Image description" },
player: {
url: "https://...",
width: 640,
height: 360,
stream: "https://...",
streamContentType: "video/mp4"
},
app: {
iphone: { id: "123456", url: "app://...", name: "App Name" },
ipad: { id: "123456", url: "app://..." },
googleplay: { id: "com.example", url: "app://..." },
country: "US"
},
}
`

$3

Standard HTML meta tags and document information.

`typescript
{
title: "Document Title", //