Firecrawl Browserless Adapter (POC)

Thin adapter that mimics a subset of the Firecrawl API using:

Direct HTTP fetch for SSR/static pages.
Browserless (headless Chromium) as fallback / SPA renderer.
Readability + Turndown to extract clean Markdown.

Tech stack:

NestJS, TypeScript, hexagonal architecture.
Vitest for tests.
Docker + docker-compose only; no host dependencies required.

Endpoints:

GET /v1/health -> { success: true, status: "ok", service: "firecrawl-browserless-adapter" }
POST /v1/scrape
- Body: { url: string, render?: boolean }
- Response: { url, title, markdown, html?, metadata: { source } }

Usage (local):

docker compose up --build
curl http://localhost:3000/v1/health
curl -X POST http://localhost:3000/v1/scrape -H "Content-Type: application/json" -d '{"url": "https://example.com"}'

SPA / render mode:

Set render=true to force Browserless for SPAs.
Without it, the adapter tries direct fetch first and falls back if content looks incomplete.

Notes:

This is a POC; not production-hardened.
No auth, no rate limiting, basic error handling only.