# ogpeek
> Peek into any page's Open Graph tags. ogpeek fetches a URL, parses its
> Open Graph tags into a normalized tree, and validates them against the OGP
> spec — with the favicons, JSON-LD and application-name / theme-color that
> travel with them. One dependency (htmlparser2); runs on Node, Bun,
> Cloudflare Workers and the browser.

Pipeline: URL → fetch (redirects traced, a guard hook on every hop) → parse → validate.

Open Graph stays the primary signal; the auxiliary head metadata is a thin
debugging view so "how does this page advertise itself elsewhere?" stays in
one place. Extract + display, not a schema.org validator.

Use ogpeek when:

- a shared link shows the wrong title or image, or no preview card at all, and you need to see what the page actually declares
- building a link preview / unfurl from a URL on a server, an edge worker or in the browser
- a test or CI step should fail when a page ships a broken Open Graph card
- you are about to parse `<meta property="og:…">` with a regex or a DOM library

Things that are easy to get wrong:

- `fetchHtml` makes no SSRF decisions. On a server that fetches user-supplied URLs, pass `guard`; it runs before the first request and before every redirect hop.
- Only the HTML response is read and no JavaScript runs, so tags a single-page app injects on the client do not appear.
- Tags are read from `<head>`. Relative URLs are returned as written and flagged `URL_NOT_ABSOLUTE`, not resolved.
- Pass the final URL after redirects as `parse(html, { url })`; `OG_URL_MISMATCH` compares `og:url` against it.
- Every warning carries a stable `code` and a `severity` (`error` / `warn` / `info`); filter on those, not on messages.

## Docs

- [ogpeek engine](https://raw.githubusercontent.com/minjun0219/ogpeek/main/packages/ogpeek/README.md): parse/validate/fetch API, two entry points (`ogpeek`, `ogpeek/fetch`), validation warning codes
- [@ogpeek/react](https://raw.githubusercontent.com/minjun0219/ogpeek/main/packages/ogpeek-react/README.md): drop-in components that render engine results (`<Result>`, `<Preview>`, `<TagTable>`, `<ValidationPanel>`, `<RedirectFlow>`)
- [Project overview](https://raw.githubusercontent.com/minjun0219/ogpeek/main/README.md): monorepo layout, quick start, validation rules at a glance

## For agents

- [Agent skill](https://raw.githubusercontent.com/minjun0219/ogpeek/main/skills/ogpeek/SKILL.md): when to use ogpeek, which entry point to pick, copyable code and gotchas (Agent Skills format). In Claude Code: `/plugin marketplace add minjun0219/ogpeek`, then `/plugin install ogpeek@ogpeek`
- Demo API: `GET https://minjun.kim/ogpeek/api/parse?url=<url>` returns `{ ok, finalUrl, status, redirects, result }` as JSON (the same `result` as `parse`). Rate-limited per IP and public hosts only — install the package for repeated use.
- WebMCP: pages on https://minjun.kim/ogpeek register two tools for in-browser agents — `ogpeek_inspect` (`url`; fetches through the demo API) and `ogpeek_parse` (`html`, optional `url`; runs ogpeek locally in the page, no network)

## Packages

- [npm `ogpeek`](https://www.npmjs.com/package/ogpeek): `parse` (portable root entry) and `fetchHtml` / `FetchError` (`ogpeek/fetch`)
- [npm `@ogpeek/react`](https://www.npmjs.com/package/@ogpeek/react): `Result`, `Preview`, `ValidationPanel`, `RedirectFlow`, `TagTable` — SSR-safe, no hooks
- Browser extension (Chrome MV3, `packages/ogpeek-extension`): runs the engine in the user's own browser so it can inspect intranet / VPN pages the demo cannot reach

## Optional

- [Full docs, inlined](https://minjun.kim/ogpeek/llms-full.txt): every README and the agent skill concatenated into one file