handleOGFetch – Once UI

The handleOGFetch function is a server-side utility that fetches and parses Open Graph metadata from any URL. It takes a standard Request and returns a Response, so it works in any server that speaks the Fetch API, and extracts title, description, image, and favicon information from web pages.

In a Next.js app, use createOgFetchRoute from @once-ui-system/core/next: a two-line route file built on this function. See OG route handlers.

Features

Fetches HTML pages only, up to a byte limit, within a timeout
Extracts Open Graph metadata (title, description, image, favicon)
Falls back to standard HTML meta tags if OG tags aren't available
Returns image and faviconUrl as absolute URLs, resolved against the page
Decodes HTML entities in text content
Supports custom user agents
Only requests public addresses: private, loopback, link-local and metadata addresses are refused in every encoding, every redirect is checked again, and the connection goes to the address that was checked
Domain allowlist and blocklist, plus an isAllowed hook for your own checks
Requires Node.js runtime (resolves and checks hostnames)

Basic usage

Create an API route that uses the utility:

app/api/og/fetch/route.ts

import { NextRequest } from 'next/server';
import { handleOGFetch } from '@once-ui-system/core/server';

export const runtime = 'nodejs';

export async function GET(request: NextRequest) {
return handleOGFetch(request);
}

Then fetch metadata from your client:

Component.tsx

const response = await fetch(
`/api/og/fetch?url=${encodeURIComponent('https://example.com')}`
);
const data = await response.json();

console.log(data);
// { url, title, description, image, faviconUrl }

With options

Customize timeout, user agent, and entity decoding:

app/api/og/fetch/route.ts

import { NextRequest } from 'next/server';
import { handleOGFetch } from '@once-ui-system/core/server';

export async function GET(request: NextRequest) {
return handleOGFetch(request, {
  timeout: 5000,
  userAgent: 'MyBot/1.0',
  decodeEntities: true,
  allowedDomains: ['example.com', 'once-ui.com'],
});
}

Response format

The function returns a JSON response with the following structure:

OGData interface

interface OGData {
url: string;          // The requested URL
title: string;        // Page or OG title
description: string;  // Page or OG description
image: string;        // OG image URL
faviconUrl?: string;  // Favicon URL (optional)
}

API Reference

	Type	Default
request	Request	—
options	OGFetchOptions	—
options.timeout	number	5000
options.userAgent	string	'Mozilla/5.0 (compatible; OG-Fetcher/1.0)'
options.decodeEntities	boolean	true
options.favicon Include faviconUrl; false leaves it out so OgCard uses its own favicon source.	boolean	true
options.maxBytes HTML read, after decompression; a longer page is parsed from what was read.	number	1 MiB
options.maxRedirects Redirects followed, each checked like the first URL.	number	3
options.allowedDomains When set, only these domains (and their subdomains) are permitted.	string[]	—
options.blockedDomains These domains (and their subdomains) are refused.	string[]	—
options.isAllowed Called for every URL and redirect target after the built-in checks; return false to refuse.	(url: URL) => boolean \| Promise<boolean>	—
options.allowHttp Also fetch plain http: URLs.	boolean	false
options.cacheControl Cache-Control on successful responses.	string	'public, max-age=3600'
options.sameOrigin Refuse requests whose Origin or Referer names another host.	boolean	false

Error handling

The function returns appropriate error responses:

400: Missing URL parameter or URL failed validation (blocked domain, private IP, etc.). A hostname that does not resolve is refused the same way, so the route cannot tell a caller which internal names exist.
403: Cross-origin caller, with sameOrigin
415: The URL is not an HTML page
502: The upstream failed (error status, too many redirects)
504: The upstream did not answer within timeout
500: Not running on the Node.js runtime

Error response

{
"error": "Failed to fetch Open Graph data"
}

Use with useOgData hook

Combine with the useOgData hook for seamless client-side integration:

Component.tsx

import { useOgData } from '@once-ui-system/core';

function MyComponent() {
const { ogData, loading } = useOgData('https://example.com');

if (loading) return <div>Loading...</div>;

return (
  <div>
    <h1>{ogData?.title}</h1>
    <p>{ogData?.description}</p>
    {ogData?.image && <img src={ogData.image} alt={ogData.title} />}
  </div>
);
}