handleOGFetch – Once UI

The handleOGFetch function is a server-side utility that fetches and parses Open Graph metadata from any URL. It's designed to be used in Next.js API routes to extract title, description, image, and favicon information from web pages.

Features

Fetches HTML content from URLs with configurable timeout
Extracts Open Graph metadata (title, description, image)
Falls back to standard HTML meta tags if OG tags aren't available
Decodes HTML entities in text content
Supports custom user agents
Validates URLs to block SSRF (private IPs, localhost, non-HTTPS)
Optional domain allowlist via allowedDomains
Requires Node.js runtime (uses DNS resolution for hostname validation)

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

Prop	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.allowedDomains When set, only these domains (and their subdomains) are permitted.	string[]	—

Error handling

The function returns appropriate error responses:

400: Missing URL parameter or URL failed validation (blocked domain, private IP, etc.)
500: Failed to fetch or parse the URL

Error response

{
"error": "Failed to fetch Open Graph data",
"message": "HTTP 404: Not Found"
}

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>
);
}