Playwright Service

General-purpose headless browser API for KoffieNAS. Handles web automation, scraping, screenshots, OAuth flows, and anything needing a real browser.

Quick Start

# Build and run with Docker Compose
docker-compose up -d

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

API Endpoints

POST /browser/execute

Generic script execution - most flexible option for custom automation.

{
  "script": "async def run(page):\n    await page.goto('https://example.com')\n    return await page.content()",
  "timeout": 30
}

POST /browser/scrape

Scrape content from a page using CSS selectors.

{
  "url": "https://example.com",
  "selectors": {
    "title": "h1",
    "items": ".item-class"
  },
  "wait_for": ".loaded-indicator",
  "javascript": true,
  "timeout": 30
}

POST /browser/screenshot

Take a screenshot of a page.

{
  "url": "https://example.com",
  "full_page": false,
  "wait_for": ".content",
  "timeout": 30
}

POST /browser/oauth

Handle OAuth flows including mobile scheme redirects.

{
  "authorize_url": "https://login.example.com/oauth",
  "intercept_pattern": "postnl://*",
  "steps": [
    {"fill": "input[name='email']", "value": "{username}"},
    {"click": "button.next"},
    {"fill": "input[name='password']", "value": "{password}"},
    {"click": "button.submit"}
  ],
  "credentials": {
    "username": "user@email.com",
    "password": "secret"
  },
  "timeout": 30
}

POST /browser/interact

Step-by-step interaction with a page.

{
  "url": "https://example.com",
  "actions": [
    {"type": "fill", "selector": "input.search", "value": "hello"},
    {"type": "click", "selector": "button.submit"},
    {"type": "wait", "selector": ".results"},
    {"type": "extract", "selector": ".results", "as": "results"}
  ],
  "timeout": 30
}

Supported action types:

• fill - Fill an input field
• type - Type text character by character
• click - Click an element
• wait - Wait for element to appear
• select - Select dropdown option
• extract - Extract text content
• screenshot - Capture screenshot

GET /health

Health check endpoint.

Response Format

All endpoints return:

{
  "success": true,
  "result": "..."  // or "data", "image", "intercepted_url", "extracted"
}

On error:

{
  "success": false,
  "error": "Error description"
}

Configuration

Environment variables:

• PYTHONUNBUFFERED=1 - Recommended for Docker logging

Development

# Install dependencies
pip install -r requirements.txt
playwright install chromium

# Run locally
uvicorn app.main:app --host 0.0.0.0 --port 5000 --reload