### Local Development Setup with Bun

Source: https://github.com/stackseehq/metadata-api/blob/main/README.md

Installs project dependencies and starts a development server with hot reloading using Bun. The server typically runs on http://localhost:3000.

```bash
bun install
bun run dev
```

--------------------------------

### Install Bun and Run Directly (No Docker)

Source: https://github.com/stackseehq/metadata-api/blob/main/README.md

Installs Bun on the system and then clones the repository, installs dependencies, and runs the application directly. This is an alternative deployment method for environments without Docker.

```bash
# Install Bun
curl -fsSL https://bun.sh/install | bash

# Clone and run
git clone your-repo
cd favicon-api
bun install
bun run start
```

--------------------------------

### Environment Variables Setup (.env file)

Source: https://context7.com/stackseehq/metadata-api/llms.txt

Example `.env` file demonstrating configuration for a web application. Includes settings for port, host, fallback image URL, API fallbacks, caching, request handling, CORS, security, and optional analytics.

```bash
# .env file
PORT=3000
HOST=0.0.0.0

# Default fallback image when no favicon found
DEFAULT_IMAGE_URL=https://example.com/default-favicon.png

# Use Google's favicon API as fallback (recommended)
USE_FALLBACK_API=true

# Cache control (7 days = 604800 seconds)
CACHE_CONTROL_SUCCESS=604800
CACHE_CONTROL_ERROR=604800

# Request handling
REQUEST_TIMEOUT=5000
MAX_IMAGE_SIZE=5242880
USER_AGENT=FaviconAPI/1.0

# CORS configuration
ALLOWED_ORIGINS=*

# Security
BLOCK_PRIVATE_IPS=true
MAX_REDIRECTS=5

# Optional: Analytics
VEMETRIC_TOKEN=your-token-here
VEMETRIC_HOST=https://vemetric.com
```

--------------------------------

### Install Dependencies (Bun)

Source: https://github.com/stackseehq/metadata-api/blob/main/README.md

Installs project dependencies using Bun, the JavaScript runtime. This is a prerequisite for running the development server or building the project.

```bash
bun install
```

--------------------------------

### Run Development Server (Bun)

Source: https://github.com/stackseehq/metadata-api/blob/main/README.md

Starts the development server with hot reloading enabled, using Bun. This command is used during development to see changes reflected instantly.

```bash
bun run dev
```

--------------------------------

### Get OpenGraph Image (Bash Example)

Source: https://github.com/stackseehq/metadata-api/blob/main/README.md

Demonstrates how to fetch an OpenGraph image directly from the API using `curl`. This is useful for testing or integrating the image into server-side processes.

```bash
curl "http://localhost:3000/og/github.com"
```

--------------------------------

### Resize and Convert OpenGraph Image (Bash Example)

Source: https://github.com/stackseehq/metadata-api/blob/main/README.md

Illustrates fetching an OpenGraph image with specified size and format using `curl`. This example shows how to convert the image to WebP format and resize it to 800 pixels.

```bash
curl "http://localhost:3000/og/github.com?size=800&format=webp"
```

--------------------------------

### Docker Deployment: Pre-built Image

Source: https://github.com/stackseehq/metadata-api/blob/main/README.md

Deploys the API using a pre-built Docker image from Docker Hub. Supports running with default settings or custom environment variables for configuration. Includes an example command to check API health.

```bash
# Run with default settings
docker run -d \
  -p 3000:3000 \
  --name favicon-api \
  --restart unless-stopped \
  vemetric/favicon-api

# Or run with custom configuration
docker run -d \
  -p 3000:3000 \
  --name favicon-api \
  --restart unless-stopped \
  -e PORT=3000 \
  -e DEFAULT_IMAGE_URL=https://example.com/default-favicon.png \
  -e USE_FALLBACK_API=true \
  -e CACHE_CONTROL_SUCCESS=604800 \
  -e CACHE_CONTROL_ERROR=604800 \
  -e REQUEST_TIMEOUT=5000 \
  -e MAX_IMAGE_SIZE=5242880 \
  -e ALLOWED_ORIGINS=*
  -e BLOCK_PRIVATE_IPS=true \
  vemetric/favicon-api

# Check it's running
curl http://localhost:3000/health
```

--------------------------------

### Initialize Hono Application with TypeScript

Source: https://context7.com/stackseehq/metadata-api/llms.txt

Creates a configured Hono application with routes, middleware, and CORS settings. It includes request logging and handles specific endpoints like favicon, OpenGraph, and health checks. Dependencies: './index', './lib/config'. Can be started with Bun or Node.js/Express.

```typescript
import { createApp } from './index';
import { loadConfig } from './lib/config';

const config = loadConfig();
const app = createApp(config);

// Start with Bun
Bun.serve({
  port: 3000,
  fetch: app.fetch,
});

// Or use with Node.js/Express
import { serve } from '@hono/node-server';
serve(app);
```

--------------------------------

### GET /<domain>

Source: https://github.com/stackseehq/metadata-api/blob/main/README.md

Fetches favicon and OpenGraph images for a given domain. Supports various query parameters for customization.

```APIDOC
## GET /<domain>

### Description
Fetches favicon and OpenGraph images for a given domain. Supports various query parameters for customization.

### Method
GET

### Endpoint
`/<domain>`

### Parameters
#### Query Parameters
- **size** (number) - Optional - Desired image size in pixels (16-512)
- **format** (string) - Optional - Image output format (`png`, `jpg`, `webp`)
- **response** (string) - Optional - Response format (`image` (default) or `json`)
- **default** (string) - Optional - Fallback image URL (overrides server config)

### Request Example
```bash
curl "http://localhost:3000/github.com?response=json&size=64&format=png"
```

### Response
#### Success Response (200)
- **favicon** (object) - Information about the fetched favicon.
  - `url` (string) - API URL to fetch this exact processed image.
  - `sourceUrl` (string) - Original image URL from the website.
  - `width` (number) - Image width in pixels.
  - `height` (number) - Image height in pixels.
  - `format` (string) - Image format (e.g., png, jpg, webp).
  - `bytes` (number) - File size in bytes.
  - `source` (string) - Source of the image (e.g., "link-tag", "manifest").
- **ogImage** (object | null) - Information about the fetched OpenGraph image. May be null if not found.
  - `url` (string) - API URL to fetch this exact processed image.
  - `sourceUrl` (string) - Original image URL from the website.
  - `width` (number) - Image width in pixels.
  - `height` (number) - Image height in pixels.
  - `format` (string) - Image format (e.g., png, jpg, webp).
  - `bytes` (number) - File size in bytes.
  - `source` (string) - Source of the image (e.g., "og:image", "twitter:image").
- **metadata** (object) - Page metadata extracted from meta tags.
  - `title` (string) - Page title.
  - `description` (string) - Page description.
  - `siteName` (string) - Site name.

#### Response Example
```json
{
  "favicon": {
    "url": "http://localhost:3000/github.com",
    "sourceUrl": "https://github.githubassets.com/favicons/favicon.png",
    "width": 64,
    "height": 64,
    "format": "png",
    "bytes": 1234,
    "source": "link-tag"
  },
  "ogImage": {
    "url": "http://localhost:3000/og/github.com",
    "sourceUrl": "https://github.com/images/modules/open_graph/github-logo.png",
    "width": 1200,
    "height": 630,
    "format": "png",
    "bytes": 45678,
    "source": "og:image"
  },
  "metadata": {
    "title": "GitHub: Let's build from here",
    "description": "GitHub is where over 100 million developers shape the future of software",
    "siteName": "GitHub"
  }
}
```
```

--------------------------------

### Docker Deployment Instructions

Source: https://context7.com/stackseehq/metadata-api/llms.txt

Provides commands for pulling a Docker image from Docker Hub, running the container with environment variables, checking its health, and building the image from source. Assumes a Bun runtime environment.

```bash
# Pull from Docker Hub
docker pull vemetric/favicon-api

# Run with environment variables
docker run -d \
  -p 3000:3000 \
  --name favicon-api \
  --restart unless-stopped \
  -e PORT=3000 \
  -e DEFAULT_IMAGE_URL=https://example.com/default.png \
  -e USE_FALLBACK_API=true \
  -e CACHE_CONTROL_SUCCESS=604800 \
  -e CACHE_CONTROL_ERROR=604800 \
  -e REQUEST_TIMEOUT=5000 \
  -e MAX_IMAGE_SIZE=5242880 \
  -e ALLOWED_ORIGINS=* \
  -e BLOCK_PRIVATE_IPS=true \
  vemetric/favicon-api

# Check health
curl http://localhost:3000/health

# Build from source
docker build -t favicon-api .
docker run -d -p 3000:3000 --name favicon-api favicon-api
```

--------------------------------

### Docker Deployment: Build from Source

Source: https://github.com/stackseehq/metadata-api/blob/main/README.md

Builds a Docker image from the project's source code and then runs it as a container. This is useful for development or when using a custom build.

```bash
# Build the image
docker build -t favicon-api .

# Run the locally built image
docker run -d \
  -p 3000:3000 \
  --name favicon-api \
  --restart unless-stopped \
  favicon-api
```

--------------------------------

### Run Tests (Bun)

Source: https://github.com/stackseehq/metadata-api/blob/main/README.md

Executes the project's test suite using Bun. This command is essential for verifying the functionality of the API.

```bash
bun test
```

--------------------------------

### Run Docker Container (Pre-built Image)

Source: https://github.com/stackseehq/metadata-api/blob/main/README.md

Pulls a pre-built Docker image from Docker Hub and runs it as a detached container. This is the recommended method for deploying the API.

```bash
docker run -d \
  -p 3000:3000 \
  --name favicon-api \
  --restart unless-stopped \
  vemetric/favicon-api
```

--------------------------------

### Build and Run Docker Image from Source

Source: https://github.com/stackseehq/metadata-api/blob/main/README.md

Clones the repository, builds a Docker image from the source code, and then runs it as a detached container. This method is useful for development or custom builds.

```bash
git clone https://github.com/vemetric/favicon-api.git
cd favicon-api

docker build -t favicon-api .
docker run -d \
  -p 3000:3000 \
  --name favicon-api \
  --restart unless-stopped \
  favicon-api
```

--------------------------------

### Format Code (Bun)

Source: https://github.com/stackseehq/metadata-api/blob/main/README.md

Automatically formats the project's code according to predefined style rules using Bun. This ensures code consistency across the project.

```bash
bun run format
```

--------------------------------

### Run Tests in Watch Mode (Bun)

Source: https://github.com/stackseehq/metadata-api/blob/main/README.md

Runs the test suite in watch mode using Bun, automatically re-running tests when code changes are detected. This enhances the development feedback loop.

```bash
bun test --watch
```

--------------------------------

### Lint Code (Bun)

Source: https://github.com/stackseehq/metadata-api/blob/main/README.md

Runs the linter to check for code style and potential errors using Bun. This command helps maintain code quality and consistency.

```bash
bun run lint
```

--------------------------------

### Type Check Code (Bun)

Source: https://github.com/stackseehq/metadata-api/blob/main/README.md

Performs static type checking on the project's codebase using Bun. This helps catch type-related errors early in the development process.

```bash
bun run typecheck
```

--------------------------------

### Load Environment Configuration with TypeScript

Source: https://context7.com/stackseehq/metadata-api/llms.txt

Loads and validates environment variables using Zod schema, providing default values and throwing descriptive errors for invalid configurations. Returns a strongly-typed config object. Dependencies: './lib/config'.

```typescript
import { loadConfig } from './lib/config';

try {
  const config = loadConfig();

  console.log('Port:', config.PORT);
  console.log('Request timeout:', config.REQUEST_TIMEOUT, 'ms');
  console.log('Max image size:', config.MAX_IMAGE_SIZE, 'bytes');
  console.log('Cache duration:', config.CACHE_CONTROL_SUCCESS, 'seconds');
  console.log('Use fallback API:', config.USE_FALLBACK_API);
  console.log('Block private IPs:', config.BLOCK_PRIVATE_IPS);
} catch (error) {
  console.error('Configuration error:', error.message);
  process.exit(1);
}
```

--------------------------------

### API Usage: Fetch Favicon as Image

Source: https://github.com/stackseehq/metadata-api/blob/main/README.md

Retrieves a website's favicon as an image. The request targets the favicon endpoint with a domain name. Various optional query parameters can be used to customize the output.

```bash
curl "http://localhost:3000/github.com"
```

--------------------------------

### API Usage: Fetch Favicon and OG Image Metadata as JSON

Source: https://github.com/stackseehq/metadata-api/blob/main/README.md

Fetches both the favicon and OpenGraph image metadata for a given domain, returning the information in JSON format. This includes details about the images and page metadata.

```bash
curl "http://localhost:3000/github.com?response=json"
```

--------------------------------

### Resize and Convert Favicon (Bash)

Source: https://context7.com/stackseehq/metadata-api/llms.txt

Allows resizing and format conversion of favicons on the fly. Supports a range of sizes (16-512 pixels) and output formats including PNG, JPG, WebP, ICO, and SVG. SVG files are passed through unless conversion is explicitly requested.

```bash
curl "http://localhost:3000/github.com?size=128&format=png"
```

--------------------------------

### API Usage: Convert Favicon Format

Source: https://github.com/stackseehq/metadata-api/blob/main/README.md

Converts the favicon to a specified image format (e.g., PNG, JPG, WebP) and optionally resizes it. The `format` and `size` parameters control the output.

```bash
curl "http://localhost:3000/github.com?format=png&size=128"
```

--------------------------------

### API Usage: Resize Favicon

Source: https://github.com/stackseehq/metadata-api/blob/main/README.md

Requests a favicon with a specified size in pixels. The `size` parameter controls the dimensions of the output image.

```bash
curl "http://localhost:3000/github.com?size=64"
```

--------------------------------

### API Usage: Custom Fallback Image

Source: https://github.com/stackseehq/metadata-api/blob/main/README.md

Specifies a custom fallback image URL to be used if the primary favicon cannot be fetched. This is controlled by the `default` query parameter.

```bash
curl "http://localhost:3000/example.com?default=https://mysite.com/fallback.png"
```

--------------------------------

### Fetch Favicon and Metadata (JSON)

Source: https://context7.com/stackseehq/metadata-api/llms.txt

The JSON response structure for fetching favicon and metadata. It details the favicon and ogImage objects with their respective properties and includes extracted page metadata like title, description, and siteName.

```json
{
  "favicon": {
    "url": "http://localhost:3000/github.com",
    "sourceUrl": "https://github.githubassets.com/favicons/favicon.png",
    "width": 64,
    "height": 64,
    "format": "png",
    "bytes": 1234,
    "source": "link-tag",
    "isFallback": false
  },
  "ogImage": {
    "url": "http://localhost:3000/og/github.com",
    "sourceUrl": "https://github.com/images/modules/open_graph/github-logo.png",
    "width": 1200,
    "height": 630,
    "format": "png",
    "bytes": 45678,
    "source": "og:image",
    "isFallback": false
  },
  "metadata": {
    "title": "GitHub: Let's build from here",
    "description": "GitHub is where over 100 million developers shape the future of software",
    "siteName": "GitHub"
  }
}
```

--------------------------------

### Resize and Convert Images (TypeScript)

Source: https://context7.com/stackseehq/metadata-api/llms.txt

Resizes images to a specified dimension and converts them between formats like PNG, JPG, WebP, and ICO using the Sharp library. It maintains the aspect ratio and supports SVG pass-through without rasterization unless format conversion is requested. Animated GIFs are passed through unchanged. ICO files are extracted to their largest embedded image.

```typescript
import { processImage } from './lib/image-processor';
import fs from 'fs';

const imageBuffer = fs.readFileSync('input.png');

// Resize to 64x64 and convert to WebP
const processed = await processImage(imageBuffer, {
  size: 64,
  format: 'webp',
  quality: 90
});

console.log('Output format:', processed.format);
console.log('Dimensions:', processed.width, 'x', processed.height);
console.log('File size:', processed.bytes, 'bytes');

fs.writeFileSync('output.webp', processed.data);

// SVG pass-through (no rasterization)
const svgBuffer = fs.readFileSync('icon.svg');
const svgProcessed = await processImage(svgBuffer, {});
// Returns original SVG buffer unchanged
```

--------------------------------

### Download Highest Quality Favicon (TypeScript)

Source: https://context7.com/stackseehq/metadata-api/llms.txt

Downloads the best available favicon from a list of candidates. It validates the image data using Sharp and supports both data and HTTP(S) URLs. The function respects the MAX_IMAGE_SIZE configuration and returns null if no valid favicon is found. The downloaded favicon data is returned as a Buffer.

```typescript
import { fetchBestFavicon } from './lib/favicon-finder';
import { analyzePage } from './lib/page-analyzer';
import { loadConfig } from './lib/config';

const config = loadConfig();
const pageData = await analyzePage('github.com', config);

const favicon = await fetchBestFavicon(pageData.favicons, config);

if (favicon) {
  console.log('Format:', favicon.format);
  console.log('Source:', favicon.source);
  console.log('Buffer size:', favicon.data.length, 'bytes');
  console.log('Is fallback:', favicon.isFallback);

  // favicon.data is a Buffer containing image bytes
  // Save to file:
  await Bun.write('favicon.png', favicon.data);
}
```

--------------------------------

### Fetch Favicon as Image

Source: https://context7.com/stackseehq/metadata-api/llms.txt

Retrieves the best quality favicon for a given domain. The API automatically discovers favicons from various sources and returns the image file with appropriate cache headers.

```APIDOC
## GET /:domain

### Description
Fetches the best quality favicon for the specified domain. The API automatically discovers favicons from HTML link tags, web manifests, and common locations like `/favicon.ico`. Response includes proper cache headers for CDN integration.

### Method
GET

### Endpoint
`/:domain`

### Parameters
#### Path Parameters
- **domain** (string) - Required - The domain name of the website (e.g., `github.com`).

### Request Example
```bash
curl "http://localhost:3000/github.com"
```

### Response
#### Success Response (200)
- **favicon** (image/png, image/jpeg, etc.) - The favicon image file.

#### Response Example
(Returns the raw image data for the favicon)
```

--------------------------------

### OpenGraph Image Endpoint (Direct Access)

Source: https://github.com/stackseehq/metadata-api/blob/main/README.md

Provides direct access to OpenGraph images for social previews or larger promotional content. Supports various query parameters for size, format, and response type. Use this endpoint when the OG image is explicitly needed.

```HTTP
GET /og/<domain>?response=<json|image>&size=<number>&format=<png|jpg|webp>&default=<url>
```

--------------------------------

### Fetch Favicon with Metadata as JSON

Source: https://context7.com/stackseehq/metadata-api/llms.txt

Fetches both the favicon and OpenGraph image along with extracted page metadata. Returns a JSON object containing details about the favicon, og:image, and page metadata like title and description.

```APIDOC
## GET /:domain?response=json

### Description
Retrieves comprehensive information about both the favicon and OpenGraph image in a single JSON response. Includes image dimensions, format, source type, and page metadata extracted from OpenGraph tags.

### Method
GET

### Endpoint
`/:domain`

### Query Parameters
- **response** (string) - Required - Must be set to `json` to receive a JSON response.

### Request Example
```bash
curl "http://localhost:3000/github.com?response=json"
```

### Response
#### Success Response (200)
- **favicon** (object) - Details of the favicon.
  - **url** (string) - The URL to fetch the favicon image.
  - **sourceUrl** (string) - The original URL of the favicon source.
  - **width** (integer) - Width of the favicon in pixels.
  - **height** (integer) - Height of the favicon in pixels.
  - **format** (string) - Image format (e.g., `png`, `ico`).
  - **bytes** (integer) - Size of the favicon in bytes.
  - **source** (string) - The source of the favicon (e.g., `link-tag`, `web-manifest`).
  - **isFallback** (boolean) - Whether this is a fallback favicon.
- **ogImage** (object) - Details of the OpenGraph image.
  - **url** (string) - The URL to fetch the OpenGraph image.
  - **sourceUrl** (string) - The original URL of the OpenGraph image source.
  - **width** (integer) - Width of the OpenGraph image in pixels.
  - **height** (integer) - Height of the OpenGraph image in pixels.
  - **format** (string) - Image format (e.g., `png`).
  - **bytes** (integer) - Size of the OpenGraph image in bytes.
  - **source** (string) - The source of the OpenGraph image (e.g., `og:image`).
  - **isFallback** (boolean) - Whether this is a fallback OpenGraph image.
- **metadata** (object) - Extracted page metadata.
  - **title** (string) - The title of the page.
  - **description** (string) - The description of the page.
  - **siteName** (string) - The name of the site.

#### Response Example
```json
{
  "favicon": {
    "url": "http://localhost:3000/github.com",
    "sourceUrl": "https://github.githubassets.com/favicons/favicon.png",
    "width": 64,
    "height": 64,
    "format": "png",
    "bytes": 1234,
    "source": "link-tag",
    "isFallback": false
  },
  "ogImage": {
    "url": "http://localhost:3000/og/github.com",
    "sourceUrl": "https://github.com/images/modules/open_graph/github-logo.png",
    "width": 1200,
    "height": 630,
    "format": "png",
    "bytes": 45678,
    "source": "og:image",
    "isFallback": false
  },
  "metadata": {
    "title": "GitHub: Let's build from here",
    "description": "GitHub is where over 100 million developers shape the future of software",
    "siteName": "GitHub"
  }
}
```
```

--------------------------------

### Skip Fallback Mode

Source: https://context7.com/stackseehq/metadata-api/llms.txt

Enables a mode where the API returns a 404 error if no favicon is found, instead of using fallback images. This is useful for ensuring only actual favicons are returned.

```APIDOC
## GET /:domain?skipFallback=true

### Description
When set to `true`, this option causes the API to return a 404 error if no favicon can be found, instead of attempting to use fallback images. This feature works with both favicon and OpenGraph image endpoints.

### Method
GET

### Endpoint
`/:domain`

### Query Parameters
- **skipFallback** (boolean) - Optional - If `true`, prevents the use of fallback images and results in a 404 if no favicon is found.

### Request Example
```bash
curl "http://localhost:3000/example.com?skipFallback=true"
```

### Response
#### Success Response (200)
- **favicon** (image/png, image/jpeg, etc.) - The favicon image if found.
#### Error Response (404)
- **Not Found** - Returned if `skipFallback` is `true` and no favicon can be found.

#### Response Example
(Returns the raw image data for the favicon, or a 404 status code)
```

--------------------------------

### Fetch OpenGraph Image Directly

Source: https://context7.com/stackseehq/metadata-api/llms.txt

Retrieves the OpenGraph social preview image directly. This endpoint is useful when you specifically need the large promotional image for social media sharing.

```APIDOC
## GET /og/:domain

### Description
Fetches the OpenGraph social preview image (typically 1200x630) used for social media sharing. The API searches for `og:image`, `twitter:image`, and schema.org structured data. Useful when you specifically need the large promotional image rather than the favicon.

### Method
GET

### Endpoint
`/og/:domain`

### Parameters
#### Path Parameters
- **domain** (string) - Required - The domain name of the website (e.g., `github.com`).

### Request Example
```bash
curl "http://localhost:3000/og/github.com"
```

### Response
#### Success Response (200)
- **ogImage** (image/png, image/jpeg, etc.) - The OpenGraph image file.

#### Response Example
(Returns the raw image data for the OpenGraph image)
```

--------------------------------

### Skip Fallback Mode (Bash)

Source: https://context7.com/stackseehq/metadata-api/llms.txt

Disables fallback mechanisms, returning a 404 error if a favicon cannot be found. This ensures that only actual favicons from the website are returned, useful for strict requirements.

```bash
curl "http://localhost:3000/example.com?skipFallback=true"
```

--------------------------------

### Resize and Convert Favicon

Source: https://context7.com/stackseehq/metadata-api/llms.txt

Resizes and converts a favicon to a specified size and format. Supports various image formats and size ranges, with special handling for SVG.

```APIDOC
## GET /:domain?size=<size>&format=<format>

### Description
Resizes the favicon to the specified dimensions and converts it to the desired image format. Supports a range of sizes and common image formats.

### Method
GET

### Endpoint
`/:domain`

### Query Parameters
- **size** (integer) - Optional - The desired size for the favicon in pixels (e.g., `128`). Supports sizes from 16 to 512.
- **format** (string) - Optional - The desired image format (e.g., `png`, `jpg`, `jpeg`, `webp`, `ico`, `svg`). SVG files are passed through unless format conversion is requested.

### Request Example
```bash
curl "http://localhost:3000/github.com?size=128&format=png"
```

### Response
#### Success Response (200)
- **favicon** (image/*) - The processed favicon image file in the requested format and size.

#### Response Example
(Returns the raw image data for the resized and converted favicon)
```

--------------------------------

### Analyze Web Page for Metadata (TypeScript)

Source: https://context7.com/stackseehq/metadata-api/llms.txt

Fetches HTML once to extract favicons, OpenGraph images, and metadata. It handles redirects and uses different User-Agent headers for bot protection. The output is a structured object containing arrays of favicons and OG images, ranked by quality score, along with page metadata.

```typescript
import { analyzePage } from './lib/page-analyzer';
import { loadConfig } from './lib/config';

const config = loadConfig();
const result = await analyzePage('github.com', config, 64);

console.log('Favicons found:', result.favicons.length);
console.log('Best favicon:', result.favicons[0]);
console.log('OG images found:', result.ogImages.length);
console.log('Metadata:', result.metadata);

// Result structure:
// {
//   favicons: [
//     { url: '...', size: 64, format: 'png', source: 'link-tag', score: 150 },
//     { url: '...', size: 32, format: 'ico', source: 'fallback', score: 10 }
//   ],
//   ogImages: [
//     { url: '...', width: 1200, height: 630, source: 'og:image', score: 240 }
//   ],
//   metadata: {
//     title: 'GitHub: Let\'s build from here',
//     description: 'GitHub is where over 100 million developers...',
//     siteName: 'GitHub'
//   }
// }
```

--------------------------------

### Health Check Endpoint (Bash)

Source: https://context7.com/stackseehq/metadata-api/llms.txt

Provides a simple health check for the API server. It returns a JSON object with the status and a timestamp, useful for monitoring and load balancer health checks.

```bash
curl "http://localhost:3000/health"
```

--------------------------------

### Custom Fallback Image

Source: https://context7.com/stackseehq/metadata-api/llms.txt

Allows specifying a custom fallback image URL. If the favicon cannot be fetched, the API will return the provided default image instead.

```APIDOC
## GET /:domain?default=<url>

### Description
Overrides the server's default fallback image for this request. If the favicon cannot be fetched, the API returns the specified custom default image instead. The custom default is processed with the same size/format options as regular favicons.

### Method
GET

### Endpoint
`/:domain`

### Query Parameters
- **default** (string) - Optional - The URL of a custom fallback image to use if the favicon cannot be found.

### Request Example
```bash
curl "http://localhost:3000/example.com?default=https://mysite.com/fallback.png"
```

### Response
#### Success Response (200)
- **favicon** (image/png, image/jpeg, etc.) - The favicon image or the custom fallback image if the favicon could not be fetched.

#### Response Example
(Returns the raw image data for the favicon or the custom fallback)
```

--------------------------------

### Discover All Favicon Sources (TypeScript)

Source: https://context7.com/stackseehq/metadata-api/llms.txt

Discovers favicons from various sources including link tags, web manifests, and common fallback paths. It assigns a quality score based on size, format, and source type, returning a sorted array with the highest quality favicons first. It can optionally use Google's favicon API as a last resort.

```typescript
import { findFavicons } from './lib/favicon-finder';
import { loadConfig } from './lib/config';

const config = loadConfig();
const favicons = await findFavicons('example.com', config, 64);

favicons.forEach(favicon => {
  console.log(`Score: ${favicon.score}`);
  console.log(`Source: ${favicon.source}`);
  console.log(`URL: ${favicon.url}`);
  console.log(`Size: ${favicon.size}px`);
  console.log(`Format: ${favicon.format}`);
  console.log('---');
});

// Typical sources (highest to lowest priority):
// - SVG files: score 150+
// - Large PNG (512px+): score 140+
// - Apple touch icons: score 60+
// - Manifest icons: score 40
// - Common paths (/favicon.ico): score 10-20
// - Google API fallback: score 1
```

--------------------------------

### Use OpenGraph Image in HTML

Source: https://github.com/stackseehq/metadata-api/blob/main/README.md

Shows how to embed an OpenGraph image directly into an HTML `<img>` tag for social previews. The `src` attribute points to the API endpoint, with optional parameters for resizing.

```html
<img src="http://localhost:3000/og/github.com?size=600" alt="GitHub preview">
```

--------------------------------

### OpenGraph Image Endpoint

Source: https://github.com/stackseehq/metadata-api/blob/main/README.md

Provides direct access to OpenGraph images for a given domain. This endpoint is useful when you specifically need the social preview image, which is typically larger than a favicon.

```APIDOC
## GET /og/<domain>

### Description
Retrieves the OpenGraph image for a specified domain. This is ideal for social media previews and larger promotional images.

### Method
GET

### Endpoint
`/og/<domain>`

### Parameters
#### Path Parameters
- **domain** (string) - Required - The domain for which to fetch the OpenGraph image.

#### Query Parameters
- **response** (string) - Optional - Specifies the response format. Accepts `json` or `image` (default).
- **size** (number) - Optional - Desired image size in pixels (16-512).
- **format** (string) - Optional - Image output format. Accepts `png`, `jpg`, or `webp`.
- **default** (string) - Optional - A fallback image URL to use if the OpenGraph image cannot be found.

### Request Example
```bash
curl "http://localhost:3000/og/github.com?size=600&format=webp"
```

### Response
#### Success Response (200)
- **image** (binary) - The OpenGraph image data.
- **json** (object) - Metadata about the OpenGraph image, including URL, type, and dimensions.

#### Response Example
*Image response (binary data)*

*JSON response example:*
```json
{
  "url": "https://example.com/og-image.jpg",
  "type": "image/jpeg",
  "width": 1200,
  "height": 630
}
```
```

--------------------------------

### Extract OpenGraph Images with TypeScript

Source: https://context7.com/stackseehq/metadata-api/llms.txt

Finds and extracts OpenGraph images from meta tags and structured data. It ranks images by source priority and size, resolving relative URLs to absolute. Returns an empty array if no images are found. Dependencies: './lib/og-finder', './lib/config'.

```typescript
import { findOGImages } from './lib/og-finder';
import { loadConfig } from './lib/config';

const config = loadConfig();
const ogImages = await findOGImages('github.com', config);

ogImages.forEach(image => {
  console.log(`Score: ${image.score}`);
  console.log(`Source: ${image.source}`);
  console.log(`URL: ${image.url}`);
  console.log(`Dimensions: ${image.width}x${image.height}`);
  console.log(`Alt text: ${image.alt}`);
  console.log('---');
});

// Extracts from:
// - og:image, og:image:url, og:image:secure_url
// - twitter:image
// - JSON-LD schema.org structured data
```

--------------------------------

### Health Check Endpoint

Source: https://context7.com/stackseehq/metadata-api/llms.txt

A simple endpoint to check the health status of the API server. It returns the current status and timestamp.

```APIDOC
## GET /health

### Description
Provides a health check status for the API server. It returns a JSON object indicating the server's operational status and the current timestamp.

### Method
GET

### Endpoint
`/health`

### Request Example
```bash
curl "http://localhost:3000/health"
```

### Response
#### Success Response (200)
- **status** (string) - The health status of the server (e.g., `ok`).
- **timestamp** (string) - The current server time in ISO 8601 format.

#### Response Example
```json
{
  "status": "ok",
  "timestamp": "2025-11-04T10:15:30.123Z"
}
```
```

--------------------------------

### Health Check Endpoint Response (JSON)

Source: https://context7.com/stackseehq/metadata-api/llms.txt

The expected JSON response from the health check endpoint. It indicates the server's operational status and the current time.

```json
{
  "status": "ok",
  "timestamp": "2025-11-04T10:15:30.123Z"
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.