### Install and Run Local Development Server

Source: https://github.com/lindoai/landing-page-scorecard/blob/main/README.md

Installs project dependencies, starts the development server, and runs type checking. Use this for local development and testing.

```bash
npm install
npm run dev
npm run typecheck
```

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

### Install Dependencies

Source: https://github.com/lindoai/landing-page-scorecard/blob/main/_autodocs/INDEX.md

Installs all necessary packages for the project.

```bash
npm install
```

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

### Example Route Handler

Source: https://github.com/lindoai/landing-page-scorecard/blob/main/_autodocs/external-dependencies.md

An example demonstrating how to use context methods and properties to handle a request and access environment variables.

```APIDOC
## Example Route Handler

### Description

This example illustrates a typical route handler that extracts a query parameter, retrieves a header, accesses an environment variable, and returns a JSON response or an error.

### Endpoint Example

```typescript
app.get('/api/score', async (c) => {
  const url = c.req.query('url') ?? '';
  const ip = c.req.header('CF-Connecting-IP');
  const siteKey = c.env.TURNSTILE_SITE_KEY;
  
  if (!url) {
    return c.status(400).json({ error: 'URL required' });
  }
  
  return c.json({ url, score: 75 });
});
```
```

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

### Example API Requests

Source: https://github.com/lindoai/landing-page-scorecard/blob/main/_autodocs/errors.md

Demonstrates example curl commands for triggering errors and successful responses for the API.

```bash
# Error
curl 'https://api.example.com/api/score'
```

```bash
# Success
curl 'https://api.example.com/api/score?url=example.com'
```

```bash
# Error (no token)
curl 'https://api.example.com/api/score?url=example.com'
```

```bash
# Success (with valid token)
curl 'https://api.example.com/api/score?url=example.com&turnstile-token=...'
```

```bash
# Error (domain doesn't exist)
curl 'https://api.example.com/api/score?url=nonexistent-domain-12345.com'
```

```bash
# Error (domain exists but server is down)
curl 'https://api.example.com/api/score?url=unreachable.internal'
```

```bash
# Success
curl 'https://api.example.com/api/score?url=example.com'
```

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

### Install Project Dependencies

Source: https://github.com/lindoai/landing-page-scorecard/blob/main/_autodocs/configuration.md

Run this command in the project directory to install all necessary packages listed in `package.json`. This also generates `package-lock.json`.

```bash
cd landing-page-scorecard
npm install
```

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

### Run Local Development Server

Source: https://github.com/lindoai/landing-page-scorecard/blob/main/_autodocs/INDEX.md

Starts a local development server for testing and debugging. Accessible at http://localhost:8787.

```bash
npm run dev
```

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

### GET /

Source: https://github.com/lindoai/landing-page-scorecard/blob/main/_autodocs/endpoints.md

Serves the HTML user interface for the landing page scorecard tool, including an interactive form and Turnstile CAPTCHA.

```APIDOC
## GET /

### Description
Serves the HTML user interface for the landing page scorecard tool.

### Method
GET

### Endpoint
/

### Response
#### Success Response (200)
- **Content-Type**: text/html - HTML page with embedded UI and Turnstile CAPTCHA
```

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

### Project Navigation Structure

Source: https://github.com/lindoai/landing-page-scorecard/blob/main/_autodocs/MANIFEST.md

Defines the hierarchical structure of the project's documentation files, guiding users through different aspects of the project.

```markdown
README.md (Start Here)
├── project-overview.md (Architecture & Overview)
├── endpoints.md (HTTP API)
├── api-reference.md (Functions & Classes)
├── types.md (Type Definitions)
├── configuration.md (Setup & Config)
├── errors.md (Error Handling)
└── external-dependencies.md (Libraries & Frameworks)
```

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

### Handle API Request with Context

Source: https://github.com/lindoai/landing-page-scorecard/blob/main/_autodocs/external-dependencies.md

Example of a route handler that accesses request query parameters, headers, and environment variables. It returns a JSON response or an error if the URL is missing.

```typescript
app.get('/api/score', async (c) => {
  const url = c.req.query('url') ?? '';
  const ip = c.req.header('CF-Connecting-IP');
  const siteKey = c.env.TURNSTILE_SITE_KEY;
  
  if (!url) {
    return c.status(400).json({ error: 'URL required' });
  }
  
  return c.json({ url, score: 75 });
});
```

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

### Contributor Reading Path

Source: https://github.com/lindoai/landing-page-scorecard/blob/main/_autodocs/MANIFEST.md

A recommended reading path for project contributors, guiding them through the project's overview, API reference, types, and configuration.

```markdown
project-overview.md → api-reference.md → types.md → configuration.md
```

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

### Manual API Testing

Source: https://github.com/lindoai/landing-page-scorecard/blob/main/_autodocs/project-overview.md

Tests the API endpoint by sending a GET request with a URL parameter. This is used for manual verification of the scoring functionality.

```bash
curl 'http://localhost:8787/api/score?url=example.com'
```

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

### Successful Score Request

Source: https://github.com/lindoai/landing-page-scorecard/blob/main/_autodocs/errors.md

An example of a successful request to the API, including the URL, a valid Turnstile token, and the resulting score breakdown.

```bash
curl 'https://api.example.com/api/score?url=example.com&turnstile-token=valid_token'
```

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

### Count Pricing Signal Matches

Source: https://github.com/lindoai/landing-page-scorecard/blob/main/_autodocs/types.md

Example of using the pricingPattern to count occurrences of pricing-related keywords and symbols within a given text. This is used for calculating the pricing score of a landing page.

```typescript
const text = "our pricing starts at $29 per month";
countMatches(text, pricingPattern);  // 2 matches: "pricing", "$"
```

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

### Handle Turnstile Token Verification

Source: https://github.com/lindoai/landing-page-scorecard/blob/main/_autodocs/types.md

Example of how to use the TurnstileVerificationResult to determine if a token is valid. If the token is invalid, it returns a 403 error.

```typescript
const captcha = await verifyTurnstileToken(c.env, token, ip);
if (!captcha.ok) {
  return c.json({ error: captcha.error }, 403);
}
// Continue processing
```

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

### Add CORS Middleware

Source: https://github.com/lindoai/landing-page-scorecard/blob/main/_autodocs/external-dependencies.md

Apply the `cors` middleware to handle cross-origin requests for specific routes. This example enables CORS for all routes under `/api/*`.

```typescript
import { cors } from 'hono/cors';

app.use('/api/*', cors());
```

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

### Main API Endpoint

Source: https://github.com/lindoai/landing-page-scorecard/blob/main/_autodocs/INDEX.md

Use this GET endpoint to retrieve the landing page score. Include the URL of the page to analyze and a Turnstile token for verification.

```http
GET /api/score?url=<url>&turnstile-token=<token>
```

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

### Health Check Endpoint

Source: https://github.com/lindoai/landing-page-scorecard/blob/main/_autodocs/configuration.md

Use the `GET /health` endpoint for monitoring and load balancer health checks. It returns a JSON object with an `ok` status.

```bash
curl https://lindo-free-tool-landing-page-scorecard.workers.dev/health
```

```json
{"ok":true}
```

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

### Count Trust Signal Matches

Source: https://github.com/lindoai/landing-page-scorecard/blob/main/_autodocs/types.md

Example of using the trustPattern to count occurrences of trust-related keywords within a given text. This is used for calculating the trust score of a landing page.

```typescript
const text = "Read our customer testimonials and case studies";
countMatches(text, trustPattern);  // 2 matches: "customer", "case study"
```

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

### Application Usage: Initialize Tool Page

Source: https://github.com/lindoai/landing-page-scorecard/blob/main/_autodocs/external-dependencies.md

Demonstrates how to use 'turnstileSiteKeyFromEnv' and 'renderTextToolPage' to set up the main page of the application. The site key is passed to the rendering function, which may be undefined during development.

```typescript
import { turnstileSiteKeyFromEnv, renderTextToolPage } from '../../_shared/tool-page';

app.get('/', (c) => {
  return c.html(renderTextToolPage({
    title: 'Landing Page Scorecard',
    description: 'Score a landing page across messaging, SEO, trust, CTA, and offer signals.',
    endpoint: '/api/score',
    sample: '{ "total": 78, "categories": { "seo": 20 } }',
    siteKey: turnstileSiteKeyFromEnv(c.env),
    buttonLabel: 'Score',
    toolSlug: 'landing-page-scorecard'
  }));
});

```

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

### Deploy Application

Source: https://github.com/lindoai/landing-page-scorecard/blob/main/README.md

Deploys the application. Ensure you have the necessary environment variables configured for production.

```bash
npm run deploy
```

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

### GET /health

Source: https://github.com/lindoai/landing-page-scorecard/blob/main/_autodocs/endpoints.md

A health check endpoint used for monitoring and load balancing purposes.

```APIDOC
## GET /health

### Description
Health check endpoint for monitoring and load balancing.

### Method
GET

### Endpoint
/health

### Response
#### Success Response (200)
- **Content-Type**: application/json - Health status

#### Response Example
```json
{
  "ok": true
}
```
```

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

### Import and Use Hono Application

Source: https://github.com/lindoai/landing-page-scorecard/blob/main/_autodocs/api-reference.md

Demonstrates how to import the default Hono application instance for deployment on Cloudflare Workers.

```typescript
import app from './index.ts';

// The app is automatically deployed to Cloudflare Workers
// Routes are handled by the Hono framework
```

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

### Initialize Hono Application Instance

Source: https://github.com/lindoai/landing-page-scorecard/blob/main/_autodocs/api-reference.md

Sets up the main Hono application instance for Cloudflare Workers, including environment bindings for Turnstile keys.

```typescript
type Env = { Bindings: { TURNSTILE_SITE_KEY?: string; TURNSTILE_SECRET_KEY?: string } };
const app = new Hono<Env>();
export default app;
```

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

### Wrangler Configuration File (`wrangler.jsonc`)

Source: https://github.com/lindoai/landing-page-scorecard/blob/main/_autodocs/configuration.md

Specifies worker name, entry point, development mode, compatibility date, and observability settings.

```jsonc
{
  "name": "lindo-free-tool-landing-page-scorecard",
  "main": "src/index.ts",
  "workers_dev": true,
  "compatibility_date": "2025-11-17",
  "observability": {
    "enabled": true
  }
}
```

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

### Initialize Hono App

Source: https://github.com/lindoai/landing-page-scorecard/blob/main/_autodocs/external-dependencies.md

Instantiate the Hono application. Use the generic type parameter to specify the environment bindings.

```typescript
import { Hono } from 'hono';

const app = new Hono<Env>();
app.get('/', (c) => c.html('...'));
export default app;
```

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

### RegExp Usage in Application

Source: https://github.com/lindoai/landing-page-scorecard/blob/main/_autodocs/types.md

Shows how to use regular expressions with string methods like match and replace for pattern matching and text normalization.

```typescript
const text = "hello world";
const matches = text.match(/l/g);  // ["l", "l", "l"]
const matches2 = text.match(/z/g);  // null

// Text normalization
const normalized = text.replace(/\s+/g, ' ');  // Collapse whitespace
```

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

### API Score Error Response Format

Source: https://github.com/lindoai/landing-page-scorecard/blob/main/_autodocs/project-overview.md

Example JSON structure for an error response from the /api/score endpoint, indicating a problem with the request or processing.

```json
{
  "error": "Error message"
}
```

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

### URL Type Usage

Source: https://github.com/lindoai/landing-page-scorecard/blob/main/_autodocs/types.md

Demonstrates creating a new URL object and converting it to a string.

```typescript
const url = new URL("https://example.com");
const normalized = url.toString();  // "https://example.com/"
```

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

### GET /api/score

Source: https://github.com/lindoai/landing-page-scorecard/blob/main/_autodocs/endpoints.md

Analyzes a landing page URL and returns a structured scorecard with category scores and metadata. Requires Turnstile CAPTCHA verification.

```APIDOC
## GET /api/score

### Description
Analyzes a landing page URL and returns a structured scorecard with category scores and metadata.

### Method
GET

### Endpoint
/api/score

### Parameters
#### Query Parameters
- **url** (string) - Required - Full or relative URL of the landing page to score. Accepts `https://example.com` or `example.com` (auto-prefixed with `https://`)
- **turnstile-token** (string) - Required - Turnstile CAPTCHA token for verification (can also be provided via header)

#### Request Headers
- **CF-Connecting-IP** (string) - Optional - Client IP address for Turnstile verification (automatically set by Cloudflare)

### Response
#### Success Response (200)
- **url** (string) - The scored URL.
- **total** (integer) - The overall score.
- **categories** (object) - Scores for different categories.
  - **seo** (integer)
  - **messaging** (integer)
  - **trust** (integer)
  - **cta** (integer)
  - **offer** (integer)
- **details** (object) - Additional details about the landing page.
  - **title** (string)
  - **description** (string)
  - **ctaCount** (integer)
  - **trustSignals** (integer)
  - **pricingSignals** (integer)

#### Response Example (Success)
```json
{
  "url": "https://example.com/",
  "total": 78,
  "categories": {
    "seo": 20,
    "messaging": 15,
    "trust": 12,
    "cta": 20,
    "offer": 11
  },
  "details": {
    "title": "Example Domain",
    "description": "Example Domain. This domain is for use in examples and documentation.",
    "ctaCount": 5,
    "trustSignals": 2,
    "pricingSignals": 1
  }
}
```

#### Error Response (400)
- **error** (string) - Message indicating URL validation failed or URL parameter missing.

#### Error Response (403)
- **error** (string) - Message indicating CAPTCHA verification failed or token invalid.

#### Error Response (502)
- **error** (string) - Message indicating page fetch failed (network error, page unreachable, etc.).
```

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

### Package.json Metadata and Scripts

Source: https://github.com/lindoai/landing-page-scorecard/blob/main/_autodocs/configuration.md

Defines project metadata, including name, version, module type, and license. Also specifies scripts for development, deployment, and type checking.

```json
{
  "name": "landing-page-scorecard",
  "version": "0.1.0",
  "type": "module",
  "license": "MIT",
  "scripts": {
    "dev": "wrangler dev",
    "deploy": "wrangler deploy",
    "typecheck": "tsc --noEmit"
  },
  "dependencies": {
    "hono": "^4.12.14",
    "linkedom": "^0.18.12"
  },
  "devDependencies": {
    "@cloudflare/workers-types": "^4.20251125.0",
    "typescript": "^5.9.3",
    "wrangler": "^4.83.0"
  }
}
```

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

### Backend/DevOps Reading Path

Source: https://github.com/lindoai/landing-page-scorecard/blob/main/_autodocs/MANIFEST.md

A recommended reading path for backend developers and DevOps personnel, covering architecture, configuration, and dependencies.

```markdown
project-overview.md → configuration.md → external-dependencies.md
```

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

### API Score Success Response Format

Source: https://github.com/lindoai/landing-page-scorecard/blob/main/_autodocs/project-overview.md

Example JSON structure for a successful response from the /api/score endpoint, detailing the landing page's scorecard.

```json
{
  "url": "https://example.com/",
  "total": 78,
  "categories": {
    "seo": 20,
    "messaging": 15,
    "trust": 12,
    "cta": 20,
    "offer": 11
  },
  "details": {
    "title": "Page Title",
    "description": "Meta description",
    "ctaCount": 5,
    "trustSignals": 3,
    "pricingSignals": 2
  }
}
```

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

### Fetch HTML and Parse with Linkedom

Source: https://github.com/lindoai/landing-page-scorecard/blob/main/_autodocs/external-dependencies.md

Shows how to fetch HTML from a URL, parse it using `parseHTML`, and extract specific elements like the title, meta description, and count links/buttons.

```typescript
import { parseHTML } from 'linkedom';

const html = await fetchHtml('https://example.com');
const { document } = parseHTML(html);

// Extract title
const title = document.title;  // "Example Domain"

// Extract meta description
const description = document
  .querySelector('meta[name="description"]')
  ?.getAttribute('content') || '';

// Count links and buttons
const ctaCount = document.querySelectorAll('a,button').length;

// Get all text (for keyword matching)
const text = (document.body?.textContent || '')
  .replace(/\s+/g, ' ')
  .toLowerCase();

const hasTestimonials = /testimonial/.test(text);
```

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

### Hono Class

Source: https://github.com/lindoai/landing-page-scorecard/blob/main/_autodocs/external-dependencies.md

The `Hono` class is the main entry point for creating a Hono application. It allows you to define routes and middleware.

```APIDOC
## Hono Class

### Description

The `Hono` class is the core of the Hono framework, used to instantiate your web application. It provides methods for defining routes and applying middleware.

### Methods

- **`get(path: string, handler: Handler)`**: Defines a GET route.
- **`use(path: string, middleware: MiddlewareHandler)`**: Applies middleware to a specified path.
- **`route(path: string, app: HonoRequest)`**: Mounts a sub-application.

### Usage Example

```typescript
import { Hono } from 'hono';

const app = new Hono();
app.get('/', (c) => c.text('Hello Hono!'));
export default app;
```
```

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

### API Integrator Reading Path

Source: https://github.com/lindoai/landing-page-scorecard/blob/main/_autodocs/MANIFEST.md

A recommended reading path for API integrators, focusing on essential documentation for integrating with the project's API.

```markdown
README.md → endpoints.md → types.md → errors.md
```

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

### npm Script Usage

Source: https://github.com/lindoai/landing-page-scorecard/blob/main/_autodocs/configuration.md

Common commands to run defined npm scripts for development, type checking, and deployment.

```bash
npm run dev         # Development
npm run typecheck   # Type checking
npm run deploy      # Production deployment
```

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

### UI Page

Source: https://github.com/lindoai/landing-page-scorecard/blob/main/_autodocs/project-overview.md

Serves the main UI page for the application.

```APIDOC
## GET /

### Description
Serves the main UI page for the application.

### Method
GET

### Endpoint
/

### Response
#### Success Response (200)
This endpoint returns the main HTML page for the application.
```

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

### Handle API Error Response

Source: https://github.com/lindoai/landing-page-scorecard/blob/main/_autodocs/types.md

Example of fetching data from the /api/score endpoint and handling potential errors. It checks the response status and parses the JSON body to extract the error message.

```typescript
const response = await fetch('/api/score?url=invalid');
if (!response.ok) {
  const error: ErrorResponse = await response.json();
  console.error(`Error: ${error.error}`);  // "A valid http(s) URL is required."
}
```

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

### UI Page Rendering

Source: https://github.com/lindoai/landing-page-scorecard/blob/main/_autodocs/README.md

Renders the main UI page for the application.

```APIDOC
## GET /

### Description
Renders the main UI page for the application.

### Method
GET

### Endpoint
/

### Parameters
None explicitly documented.
```

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

### Consume Score Response Data

Source: https://github.com/lindoai/landing-page-scorecard/blob/main/_autodocs/types.md

Example of fetching data from the `/api/score` endpoint and parsing the JSON response into the `ScoreResponse` type. Logs the total score and SEO category score to the console.

```typescript
const response = await fetch('/api/score?url=example.com&turnstile-token=TOKEN');
const data: ScoreResponse = await response.json();

console.log(`Total Score: ${data.total}/100`);
console.log(`SEO: ${data.categories.seo}/20`);
console.log(`Page Title: ${data.details.title}`);
```

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

### Get Landing Page Score

Source: https://github.com/lindoai/landing-page-scorecard/blob/main/_autodocs/project-overview.md

Retrieves a score for a given landing page URL. Requires a URL and a Turnstile CAPTCHA token for verification. The score is broken down into categories and detailed metrics.

```APIDOC
## GET /api/score

### Description
Retrieves a score for a given landing page URL. Requires a URL and a Turnstile CAPTCHA token for verification. The score is broken down into categories and detailed metrics.

### Method
GET

### Endpoint
/api/score

### Parameters
#### Query Parameters
- **url** (string) - Required - The URL of the landing page to score.
- **turnstile-token** (string) - Required - Token from the Turnstile CAPTCHA widget.

### Response
#### Success Response (200)
- **url** (string) - The URL that was scored.
- **total** (integer) - The overall score for the landing page.
- **categories** (object) - An object containing scores for different categories (seo, messaging, trust, cta, offer).
  - **seo** (integer)
  - **messaging** (integer)
  - **trust** (integer)
  - **cta** (integer)
  - **offer** (integer)
- **details** (object) - An object containing detailed metrics about the landing page.
  - **title** (string) - The page title.
  - **description** (string) - The meta description.
  - **ctaCount** (integer) - The number of calls to action.
  - **trustSignals** (integer) - The number of trust signals.
  - **pricingSignals** (integer) - The number of pricing signals.

#### Response Example
```json
{
  "url": "https://example.com/",
  "total": 78,
  "categories": {
    "seo": 20,
    "messaging": 15,
    "trust": 12,
    "cta": 20,
    "offer": 11
  },
  "details": {
    "title": "Page Title",
    "description": "Meta description",
    "ctaCount": 5,
    "trustSignals": 3,
    "pricingSignals": 2
  }
}
```

#### Error Response (400, 403, 502)
- **error** (string) - A message describing the error.

#### Response Example
```json
{
  "error": "Error message"
}
```
```

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

### Score a URL (Development)

Source: https://github.com/lindoai/landing-page-scorecard/blob/main/_autodocs/project-overview.md

Use this command to manually test the API's URL scoring functionality in a local development environment.

```bash
# In development
curl 'http://localhost:8787/api/score?url=example.com'
```

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

### Frontend Developer Reading Path

Source: https://github.com/lindoai/landing-page-scorecard/blob/main/_autodocs/MANIFEST.md

A recommended reading path for frontend developers, emphasizing configuration and API details relevant to frontend implementation.

```markdown
configuration.md → endpoints.md → types.md
```

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

### Headers Object Manipulation

Source: https://github.com/lindoai/landing-page-scorecard/blob/main/_autodocs/external-dependencies.md

The `Headers` object provides methods to manage HTTP headers, including getting, setting, checking for, and deleting header values. It supports iterating over headers using `forEach`.

```typescript
class Headers {
  constructor(init?: HeadersInit);
  get(name: string): string | null;
  set(name: string, value: string): void;
  has(name: string): boolean;
  delete(name: string): void;
  forEach(callback: (value: string, name: string) => void): void;
}
```

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

### Handle Hono Request and Respond

Source: https://github.com/lindoai/landing-page-scorecard/blob/main/_autodocs/types.md

Shows how to access request details like query parameters and headers, and how to send JSON responses within a Hono route handler. Utilize `c.req` for request data and `c.json` for responses.

```typescript
app.get('/api/score', async (c) => {
  const url = c.req.query('url');  // Get 'url' query parameter
  const ip = c.req.header('CF-Connecting-IP');  // Get header
  const env = c.env;  // Access bindings
  
  return c.json({ result: 'ok' }, 200);  // Send JSON response
});
```

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

### UI Page

Source: https://github.com/lindoai/landing-page-scorecard/blob/main/_autodocs/INDEX.md

Serves the main user interface page for the Landing Page Scorecard.

```APIDOC
## GET /

### Description
Serves the main user interface page for the Landing Page Scorecard.

### Method
GET

### Endpoint
/

```

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

### Hono Application Instance

Source: https://github.com/lindoai/landing-page-scorecard/blob/main/_autodocs/api-reference.md

The main application is exported as a default Hono instance configured for Cloudflare Workers. It includes middleware for API routes and registers several endpoints for UI, health checks, and scoring.

```APIDOC
## Application Setup

### `Hono<Env>` Instance

The main application is exported as a default Hono instance configured for Cloudflare Workers.

**Signature**

```typescript
type Env = { Bindings: { TURNSTILE_SITE_KEY?: string; TURNSTILE_SECRET_KEY?: string } };
const app = new Hono<Env>();
export default app;
```

**Type Parameters**

- `Env`: Hono context type with Cloudflare Workers bindings
  - `Bindings.TURNSTILE_SITE_KEY`: Optional Turnstile site key for UI
  - `Bindings.TURNSTILE_SECRET_KEY`: Optional Turnstile secret key for verification

**Routes Registered**

The app instance registers the following middleware and routes:

1. CORS middleware on `/api/*` paths
2. GET `/` — UI page
3. GET `/health` — Health check
4. GET `/api/score` — Scoring endpoint

**Usage Example**

```typescript
import app from './index.ts';

// The app is automatically deployed to Cloudflare Workers
// Routes are handled by the Hono framework
```
```

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

### Score a URL (Production)

Source: https://github.com/lindoai/landing-page-scorecard/blob/main/_autodocs/project-overview.md

Use this command to manually test the API's URL scoring functionality in a production environment. A valid CAPTCHA token is required.

```bash
# In production (requires valid CAPTCHA token)
curl 'https://lindo-free-tool-landing-page-scorecard.workers.dev/api/score?url=example.com&turnstile-token=...'
```

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

### Request Missing URL Parameter

Source: https://github.com/lindoai/landing-page-scorecard/blob/main/_autodocs/errors.md

This request demonstrates calling the API without the required 'url' parameter, which will result in a 400 Bad Request error.

```bash
curl 'https://api.example.com/api/score'
```

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

### Hono Context Request Handling

Source: https://github.com/lindoai/landing-page-scorecard/blob/main/_autodocs/api-reference.md

Demonstrates accessing query parameters, headers, and environment variables using the Hono context object. Useful for API route handlers.

```typescript
app.get('/api/score', async (c) => {
  const url = c.req.query('url');
  const token = c.req.header('authorization');
  const siteKey = c.env.TURNSTILE_SITE_KEY;
  
  return c.json({ url, token }, 200);
});
```

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

### Configure TURNSTILE_SITE_KEY in wrangler.jsonc

Source: https://github.com/lindoai/landing-page-scorecard/blob/main/_autodocs/configuration.md

Set the Cloudflare Turnstile public site key as a plain text environment variable binding for production deployments in wrangler.jsonc.

```json
{
  "env": {
    "production": {
      "bindings": [
        {
          "binding": "TURNSTILE_SITE_KEY",
          "type": "plain_text",
          "text": "your-site-key-here"
        }
      ]
    }
  }
}
```

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

### URL Constructor

Source: https://github.com/lindoai/landing-page-scorecard/blob/main/_autodocs/external-dependencies.md

The URL constructor provides a convenient way to parse and manipulate URLs.

```APIDOC
## URL Constructor

### Description

The `URL` constructor is used to parse and create URL objects. It provides properties to access different parts of the URL.

### Signature

```typescript
class URL {
  constructor(input: string, base?: string | URL);
  toString(): string;
  href: string;
  protocol: string;
  hostname: string;
  pathname: string;
  search: string;
  hash: string;
}
```

### Properties

- **`href`** (string): The full URL.
- **`protocol`** (string): The URL's protocol (e.g., "https:").
- **`hostname`** (string): The domain name of the URL.
- **`pathname`** (string): The path of the URL.
- **`search`** (string): The query string of the URL.
- **`hash`** (string): The fragment identifier of the URL.
```

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

### Authenticate with Cloudflare

Source: https://github.com/lindoai/landing-page-scorecard/blob/main/_autodocs/configuration.md

Logs you into Cloudflare using your browser. This command is required before deploying to Cloudflare Workers.

```bash
wrangler login
```

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

### Deploy to Cloudflare Workers

Source: https://github.com/lindoai/landing-page-scorecard/blob/main/_autodocs/INDEX.md

Deploys the application to the Cloudflare Workers environment.

```bash
npm run deploy
```

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

### Fetch HTML Content from URL

Source: https://github.com/lindoai/landing-page-scorecard/blob/main/_autodocs/api-reference.md

Fetches HTML content from a given URL, setting specific Accept and User-Agent headers. Returns null on fetch errors or non-2xx status codes.

```typescript
async function fetchHtml(url: string): Promise<string | null>
```

```typescript
const html = await fetchHtml("https://example.com");
if (html) {
  console.log(html.substring(0, 100)); // First 100 chars
} else {
  console.log("Failed to fetch or network error");
}
```

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

### Context Object Environment

Source: https://github.com/lindoai/landing-page-scorecard/blob/main/_autodocs/external-dependencies.md

Access environment variables and bindings, such as Cloudflare Workers bindings, via `c.env`.

```APIDOC
## Context Object Environment

### Description

The `c.env` property provides access to the environment bindings configured for the application, which can include secrets, variables, and other external services.

### Properties

- **`c.env`** (E['Bindings']): Access to environment-specific bindings, such as Cloudflare Workers bindings.
```

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

### fetchHtml

Source: https://github.com/lindoai/landing-page-scorecard/blob/main/_autodocs/api-reference.md

Fetches the HTML content of a URL with appropriate headers and error handling. It returns the HTML as a string on success or `null` if the fetch fails.

```APIDOC
### `fetchHtml(url: string): Promise<string | null>`

Fetches the HTML content of a URL with appropriate headers and error handling.

**Signature**

```typescript
async function fetchHtml(url: string): Promise<string | null>
```

**Parameters**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| url | string | Yes | A valid, normalized HTTPS URL to fetch |

**Returns**

- **Type:** `Promise<string | null>`
- **On Success:** The full HTML document as a string
- **On Failure:** `null` if fetch fails (network error, non-2xx status, etc.)

**Request Headers**

The function sets the following headers:

| Header | Value |
|--------|-------|
| Accept | `text/html,application/xhtml+xml` |
| User-Agent | `Lindo Free Tools/1.0 (+https://lindo.ai/tools)` |

**Error Handling**

- Catches all errors thrown by `fetch()` and returns `null`
- Checks the response status with `r.ok` (200-299 range)
- Only calls `r.text()` if the response is OK

**Examples**

```typescript
const html = await fetchHtml("https://example.com");
if (html) {
  console.log(html.substring(0, 100)); // First 100 chars
} else {
  console.log("Failed to fetch or network error");
}
```
```

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

### renderTextToolPage(options: ToolPageOptions): string

Source: https://github.com/lindoai/landing-page-scorecard/blob/main/_autodocs/api-reference.md

Renders the HTML page for the landing page scorecard UI. It accepts various options to configure the page content and behavior.

```APIDOC
## renderTextToolPage(options: ToolPageOptions): string

Renders the HTML page for the landing page scorecard UI.

**Signature**

```typescript
import { renderTextToolPage } from '../../_shared/tool-page';
function renderTextToolPage(options: {
  title: string;
  description: string;
  endpoint: string;
  sample: string;
  siteKey: string | undefined;
  buttonLabel: string;
  toolSlug: string;
}): string
```

**Parameters**

| Parameter | Type | Description |
|-----------|------|-------------|
| title | string | Page title: `"Landing Page Scorecard"` |
| description | string | Page description: `"Score a landing page across messaging, SEO, trust, CTA, and offer signals."` |
| endpoint | string | API endpoint path: `"/api/score"` |
| sample | string | Sample response to display: `'{ "total": 78, "categories": { "seo": 20 } }'` |
| siteKey | string | undefined | Turnstile site key for CAPTCHA widget (may be undefined in development) |
| buttonLabel | string | Submit button text: `"Score"` |
| toolSlug | string | Unique identifier for the tool: `"landing-page-scorecard"` |

**Returns**

- **Type:** `string`
- A complete HTML document with embedded styling and JavaScript for the UI
```

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

### Test URL Parsing

Source: https://github.com/lindoai/landing-page-scorecard/blob/main/_autodocs/errors.md

Use the URL constructor in JavaScript to validate if a URL string is correctly formatted. This can help diagnose 400 Bad Request errors.

```javascript
new URL('https://example.com')
```

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

### Making HTTP Requests with fetch

Source: https://github.com/lindoai/landing-page-scorecard/blob/main/_autodocs/external-dependencies.md

Use the `fetch` API to make outbound HTTP requests. Specify custom headers like 'User-Agent' and 'Accept' for request identification and content negotiation. Ensure to check `response.ok` before processing the response body.

```typescript
const response = await fetch('https://example.com', {
  headers: {
    'User-Agent': 'Lindo Free Tools/1.0',
    'Accept': 'text/html'
  }
});

if (response.ok) {
  const html = await response.text();
}
```

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

### fetch() API

Source: https://github.com/lindoai/landing-page-scorecard/blob/main/_autodocs/external-dependencies.md

The fetch API allows you to make HTTP requests to external resources. It returns a Promise that resolves to a Response object.

```APIDOC
## fetch() API

### Description

The `fetch()` API is used to initiate network requests. It takes a resource (URL or Request object) and optional initialization settings, returning a Promise that resolves to a `Response` object.

### Signature

```typescript
function fetch(
  resource: RequestInfo,
  init?: RequestInit
): Promise<Response>
```

### Parameters

#### `resource`

- **Type**: `string | Request`
- **Description**: The URL or Request object to fetch.

#### `init` (Optional)

- **Type**: `RequestInit`
- **Description**: An object containing settings for the request.
  - **`headers`** (object): HTTP headers to include in the request.
  - **`method`** (string): The HTTP method (e.g., GET, POST).
  - **`body`** (string | Uint8Array): The request body.

### Response Object

- **`ok`** (boolean): Indicates if the response status is in the 200-299 range.
- **`status`** (number): The HTTP status code of the response.
- **`headers`** (Headers): An object containing the response headers.
- **`text()`** (Promise<string>): Returns the response body as a string.
- **`json()`** (Promise<any>): Parses the response body as JSON.
```

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

### Parsing URLs with the URL Constructor

Source: https://github.com/lindoai/landing-page-scorecard/blob/main/_autodocs/external-dependencies.md

Utilize the `URL` constructor to parse and manipulate URLs. It provides properties like `href`, `protocol`, `hostname`, `pathname`, `search`, and `hash` for easy access to URL components.

```typescript
const url = new URL('https://example.com/path?query=value');
console.log(url.toString());  // "https://example.com/path?query=value"
```

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

### Main Endpoint

Source: https://github.com/lindoai/landing-page-scorecard/blob/main/_autodocs/INDEX.md

Retrieves the scorecard for a given URL. Requires a URL and a Turnstile token for verification.

```APIDOC
## GET /api/score

### Description
Retrieves the scorecard for a given URL.

### Method
GET

### Endpoint
/api/score

### Parameters
#### Query Parameters
- **url** (string) - Required - The URL of the page to score.
- **turnstile-token** (string) - Required - The Turnstile verification token.
```

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

### HTTP User-Agent Header

Source: https://github.com/lindoai/landing-page-scorecard/blob/main/_autodocs/endpoints.md

The user-agent string used for all HTTP requests to target landing pages. This helps identify the requests originating from the Lindo Free Tools service.

```text
Lindo Free Tools/1.0 (+https://lindo.ai/tools)
```

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

### Wrangler Configuration for Cloudflare Workers

Source: https://github.com/lindoai/landing-page-scorecard/blob/main/_autodocs/project-overview.md

This JSON configuration file sets up the basic parameters for deploying the application to Cloudflare Workers using wrangler.

```jsonc
{
  "name": "lindo-free-tool-landing-page-scorecard",
  "main": "src/index.ts",
  "workers_dev": true,
  "compatibility_date": "2025-11-17",
  "observability": { "enabled": true }
}
```

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

### Context Object Request Properties

Source: https://github.com/lindoai/landing-page-scorecard/blob/main/_autodocs/external-dependencies.md

Access request details such as URL, method, query parameters, and headers through the `c.req` object.

```APIDOC
## Context Object Request Properties

### Description

The `c.req` object within the context provides access to various properties of the incoming HTTP request.

### Properties

- **`c.req.url`** (string): The full URL of the request, including query string and fragment.
- **`c.req.method`** (string): The HTTP method used for the request (e.g., 'GET', 'POST').
- **`c.req.query(key)`** (string | undefined): Retrieves a query parameter by its key.
- **`c.req.header(name)`** (string | undefined): Retrieves a request header by its name.
- **`c.req.path`** (string): The request path, excluding the query string.
```

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

### Parse HTML and Access Document Properties

Source: https://github.com/lindoai/landing-page-scorecard/blob/main/_autodocs/types.md

Demonstrates parsing an HTML string and accessing properties like title and body content. Ensure the body element exists before accessing its text content.

```typescript
import { parseHTML } from 'linkedom';

const html = "<html><head><title>Test</title></head><body>Content</body></html>";
const { document } = parseHTML(html);

console.log(document.title);  // "Test"
console.log(document.body?.textContent);  // "Content"
const buttons = document.querySelectorAll('button');  // NodeList
```

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

### Project tsconfig.json Configuration

Source: https://github.com/lindoai/landing-page-scorecard/blob/main/_autodocs/configuration.md

This is the main TypeScript configuration file for the project. It specifies compiler options and files to include.

```json
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "strict": true,
    "skipLibCheck": true,
    "lib": ["ES2022", "WebWorker"],
    "types": ["@cloudflare/workers-types"],
    "noEmit": true
  },
  "include": ["src/**/*.ts"]
}
```

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

### Debugging Fetch Errors

Source: https://github.com/lindoai/landing-page-scorecard/blob/main/_autodocs/errors.md

Provides curl commands to help debug issues when fetching a target URL.

```bash
curl -v https://example.com
```

```bash
curl -o /dev/null -s -w "%{http_code}" https://example.com
# Should print 200
```

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

### Hono Context Type

Source: https://github.com/lindoai/landing-page-scorecard/blob/main/_autodocs/api-reference.md

The application utilizes Hono's context object, accessible in route handlers via the 'c' parameter. Key methods include 'c.html', 'c.json', 'c.req.query', 'c.req.url', 'c.req.header', and 'c.env'.

```APIDOC
## Hono Context Type

The application uses Hono's context object, available in route handlers via the `c` parameter.

**Key Methods Used**

| Method | Returns | Description |
|--------|---------|-------------|
| `c.html(html)` | `Response` | Returns an HTML response with `content-type: text/html` |
| `c.json(data, status?)` | `Response` | Returns a JSON response with optional HTTP status code |
| `c.req.query(key)` | `string | undefined` | Retrieves a query parameter |
| `c.req.url` | `string` | Returns the full request URL including query string |
| `c.req.header(name)` | `string | undefined` | Retrieves a request header |
| `c.env` | `Bindings` | Access to Cloudflare Workers bindings (environment variables) |

**Usage Example**

```typescript
app.get('/api/score', async (c) => {
  const url = c.req.query('url');
  const token = c.req.header('authorization');
  const siteKey = c.env.TURNSTILE_SITE_KEY;
  
  return c.json({ url, token }, 200);
});
```
```

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

### Enable Workers Analytics Engine

Source: https://github.com/lindoai/landing-page-scorecard/blob/main/_autodocs/configuration.md

Set `observability.enabled` to `true` in your configuration to automatically collect request metrics, performance data, error rates, and logs.

```yaml
observability.enabled: true
```

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

### Fetch Target Page - 502 Bad Gateway

Source: https://github.com/lindoai/landing-page-scorecard/blob/main/_autodocs/errors.md

Fetches the content of the target landing page. Returns a 502 error if the page cannot be fetched due to network issues, HTTP errors from the target server, timeouts, or invalid responses.

```typescript
const html = await fetchHtml(normalized);
if (!html) return c.json({ error: 'Failed to fetch page.' }, 502);
```

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

### Parse HTML String with Linkedom

Source: https://github.com/lindoai/landing-page-scorecard/blob/main/_autodocs/external-dependencies.md

Demonstrates basic usage of `parseHTML` to parse a simple HTML string and access its title.

```typescript
import { parseHTML } from 'linkedom';

const html = '<html><head><title>Test</title></head><body>Content</body></html>';
const { document } = parseHTML(html);

console.log(document.title);  // "Test"
```

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

### Render Text Tool Page

Source: https://github.com/lindoai/landing-page-scorecard/blob/main/_autodocs/api-reference.md

Generates the complete HTML document for a tool page, including UI elements, styling, and JavaScript. Requires detailed options for page content and configuration.

```typescript
import { renderTextToolPage } from '../../_shared/tool-page';
function renderTextToolPage(options: {
  title: string;
  description: string;
  endpoint: string;
  sample: string;
  siteKey: string | undefined;
  buttonLabel: string;
  toolSlug: string;
}): string
```