openclaw-crawleo-skill 0.1.0

package/contracts/crawleo-endpoints.json

@@ -0,0 +1,237 @@
+{
+  "schema_version": "1.0.0",
+  "base_url": "https://api.crawleo.dev",
+  "auth": {
+    "primary_header": "x-api-key",
+    "primary_env_var": "CRAWLEO_API_KEY",
+    "alternate_header": "Authorization: Bearer YOUR_API_KEY",
+    "secret_handling": "Never print, log, echo, or persist API key values."
+  },
+  "source_policy": {
+    "primary": "Crawleo endpoint-specific documentation",
+    "secondary": "Crawleo docs index, MCP overview, authentication docs, API introduction, and OpenAPI snapshot where it agrees",
+    "ambiguity_phrase": "not specified in Crawleo docs",
+    "notes": [
+      "Endpoint-specific docs are used where OpenAPI omits documented endpoints.",
+      "The local OpenAPI snapshot lists /search, /google-maps, and /crawl only; endpoint docs also document /google-search and /headful-browser."
+    ]
+  },
+  "mcp": {
+    "endpoint": "https://api.crawleo.dev/mcp",
+    "source": {
+      "path": ".gsd/research/crawleo-docs/md/overview.md",
+      "url": "https://docs.crawleo.dev/mcp/overview.md"
+    },
+    "tools": [
+      { "name": "search_web", "maps_to_endpoint": "/search", "documented_cost": "10 credits per page of results" },
+      { "name": "google_search", "maps_to_endpoint": "/google-search", "documented_cost": "10 credits per request" },
+      { "name": "google_maps", "maps_to_endpoint": "/google-maps", "documented_cost": "10 credits per request in MCP overview; conflicts with endpoint doc cost of 30 credits per request" },
+      { "name": "crawl_web", "maps_to_endpoint": "/crawl", "documented_cost": "1 credit per URL for HTTP request; 10 credits per URL for browser rendering" },
+      { "name": "headful_browser", "maps_to_endpoint": "/headful-browser", "documented_cost": "50 credits per URL" }
+    ]
+  },
+  "endpoints": [
+    {
+      "id": "search",
+      "name": "Bing Search API",
+      "method": "GET",
+      "path": "/search",
+      "url": "https://api.crawleo.dev/search",
+      "mcp_tool": "search_web",
+      "description": "Bing-powered real-time web search with optional auto-crawling and page content extraction for LLM/RAG workflows.",
+      "sources": [
+        { "path": ".gsd/research/crawleo-docs/md/search.md", "url": "https://docs.crawleo.dev/api-reference/endpoint/search.md" },
+        { "path": ".gsd/research/crawleo-docs/md/overview.md", "url": "https://docs.crawleo.dev/mcp/overview.md" },
+        { "path": ".gsd/research/crawleo-docs/openapi.json.json", "url": "https://docs.crawleo.dev/openapi.json" }
+      ],
+      "cost": "10 credits per page via max_pages / MCP search_web cost; exact cost for example-only count parameter is not specified in Crawleo docs",
+      "parameters": [
+        { "in": "header", "name": "x-api-key", "type": "string", "required": true, "default": null, "limits_or_enum": null, "description": "Crawleo API key; Authorization Bearer is documented as an alternative." },
+        { "in": "query", "name": "query", "type": "string", "required": true, "default": null, "limits_or_enum": null, "description": "Search query string." },
+        { "in": "query", "name": "max_pages", "type": "integer", "required": false, "default": 1, "limits_or_enum": "not specified in Crawleo docs", "description": "Maximum number of result pages to fetch; each page costs 10 credits." },
+        { "in": "query", "name": "setLang", "type": "string", "required": false, "default": null, "limits_or_enum": "examples: en, es, fr, de", "description": "Language code for search results." },
+        { "in": "query", "name": "cc", "type": "string", "required": false, "default": null, "limits_or_enum": "examples: US, GB, DE", "description": "Country code for search results." },
+        { "in": "query", "name": "geolocation", "type": "string", "required": false, "default": null, "limits_or_enum": "random is documented", "description": "Geographic location for localized results." },
+        { "in": "query", "name": "device", "type": "string", "required": false, "default": "desktop", "limits_or_enum": ["desktop", "mobile", "tablet"], "description": "Device type to simulate." },
+        { "in": "query", "name": "copilot_answer", "type": "boolean", "required": false, "default": true, "limits_or_enum": null, "description": "Include Copilot answers." },
+        { "in": "query", "name": "questions_answers", "type": "boolean", "required": false, "default": true, "limits_or_enum": null, "description": "Include People Also Ask question-answer cards." },
+        { "in": "query", "name": "related_queries", "type": "boolean", "required": false, "default": true, "limits_or_enum": null, "description": "Include related search query suggestions." },
+        { "in": "query", "name": "sidebar", "type": "boolean", "required": false, "default": true, "limits_or_enum": null, "description": "Include sidebar data such as knowledge panels and local results." },
+        { "in": "query", "name": "direct_answer", "type": "boolean", "required": false, "default": true, "limits_or_enum": null, "description": "Include direct answer boxes and instant answers." },
+        { "in": "query", "name": "raw_html", "type": "boolean", "required": false, "default": false, "limits_or_enum": null, "description": "Return original HTML source of each result page." },
+        { "in": "query", "name": "enhanced_html", "type": "boolean", "required": false, "default": false, "limits_or_enum": null, "description": "Return cleaned HTML with ads, scripts, and tracking removed." },
+        { "in": "query", "name": "page_text", "type": "boolean", "required": false, "default": false, "limits_or_enum": null, "description": "Return extracted plain text from each result page." },
+        { "in": "query", "name": "markdown", "type": "boolean", "required": false, "default": false, "limits_or_enum": null, "description": "Return structured Markdown." },
+        { "in": "query", "name": "auto_crawling", "type": "boolean", "required": false, "default": false, "limits_or_enum": null, "description": "Automatically crawl each search result URL and include page content." },
+        { "in": "query", "name": "count", "type": "integer", "required": false, "default": "not specified in Crawleo docs", "limits_or_enum": "not specified in Crawleo docs", "description": "Appears in Crawleo example requests but not in the visible parameter table." }
+      ],
+      "examples": [
+        { "label": "Basic search", "request": "GET /search?query=machine%20learning&count=10" },
+        { "label": "Markdown auto-crawling", "request": "GET /search?query=AI%20agents&auto_crawling=true&markdown=true" }
+      ],
+      "response_shape": {
+        "top_level_fields": ["query", "pages_fetched", "pages", "total_results", "search_results", "related_queries", "credits"],
+        "result_fields": ["title", "link", "date", "snippet", "source", "page_content", "enhanced_html", "page_markdown"]
+      },
+      "errors": "not specified in Crawleo docs",
+      "ambiguities": [
+        "The `count` query parameter appears in examples but is not listed in the visible parameter table.",
+        "Search endpoint error response table is not specified in Crawleo docs."
+      ]
+    },
+    {
+      "id": "google_search",
+      "name": "Google Search API",
+      "method": "GET",
+      "path": "/google-search",
+      "url": "https://api.crawleo.dev/google-search",
+      "mcp_tool": "google_search",
+      "description": "Real-time Google SERP data including web, news, images, places, shopping, knowledge graph, People Also Ask, related searches, and answer boxes.",
+      "sources": [
+        { "path": ".gsd/research/crawleo-docs/md/google-search.md", "url": "https://docs.crawleo.dev/api-reference/endpoint/google-search.md" },
+        { "path": ".gsd/research/crawleo-docs/md/overview.md", "url": "https://docs.crawleo.dev/mcp/overview.md" }
+      ],
+      "cost": "10 credits per request",
+      "parameters": [
+        { "in": "header", "name": "x-api-key", "type": "string", "required": true, "default": null, "limits_or_enum": null, "description": "Crawleo API key; Authorization Bearer is documented as an alternative." },
+        { "in": "query", "name": "q", "type": "string", "required": true, "default": null, "limits_or_enum": null, "description": "Search query." },
+        { "in": "query", "name": "gl", "type": "string", "required": false, "default": "us", "limits_or_enum": "ISO 3166-1 alpha-2 examples: us, gb, eg, de, fr", "description": "Country for search results." },
+        { "in": "query", "name": "hl", "type": "string", "required": false, "default": "en", "limits_or_enum": "IETF language tag examples: en, ar, fr, de", "description": "Language for results." },
+        { "in": "query", "name": "tbs", "type": "string", "required": false, "default": null, "limits_or_enum": ["qdr:h", "qdr:d", "qdr:w", "qdr:m", "qdr:y"], "description": "Time-based freshness filter." },
+        { "in": "query", "name": "page", "type": "integer", "required": false, "default": 1, "limits_or_enum": "1-indexed; upper bound not specified in Crawleo docs", "description": "Page number of results." },
+        { "in": "query", "name": "num", "type": "integer", "required": false, "default": 10, "limits_or_enum": "1-100", "description": "Number of results per page." },
+        { "in": "query", "name": "type", "type": "string", "required": false, "default": "search", "limits_or_enum": ["search", "news", "images", "places", "shopping"], "description": "Google result vertical." }
+      ],
+      "examples": [
+        { "label": "Basic Google search", "request": "GET /google-search?q=best%20CRM%20software&gl=us&hl=en&num=10" },
+        { "label": "News search", "request": "GET /google-search?q=AI&type=news&tbs=qdr:d" },
+        { "label": "Places search", "request": "GET /google-search?q=coffee&type=places&gl=us" },
+        { "label": "Shopping search", "request": "GET /google-search?q=laptop&type=shopping" }
+      ],
+      "response_shape": {
+        "top_level_fields": ["parameters", "google_search_results", "knowledgeGraph", "peopleAlsoAsk", "relatedSearches", "answerBox"],
+        "result_fields": ["title", "link", "snippet", "position"]
+      },
+      "errors": [
+        { "status": 400, "description": "Missing required parameter `q`" },
+        { "status": 401, "description": "Invalid or missing API key" },
+        { "status": 402, "description": "Insufficient credits" },
+        { "status": 429, "description": "Rate limit exceeded" },
+        { "status": 500, "description": "Internal server error" }
+      ],
+      "ambiguities": ["Google Search is documented in endpoint-specific docs and docs index but absent from the local OpenAPI snapshot."]
+    },
+    {
+      "id": "google_maps",
+      "name": "Google Maps API",
+      "method": "GET",
+      "path": "/google-maps",
+      "url": "https://api.crawleo.dev/google-maps",
+      "mcp_tool": "google_maps",
+      "description": "Google Maps business/place/landmark search with structured place data.",
+      "sources": [
+        { "path": ".gsd/research/crawleo-docs/md/google-maps.md", "url": "https://docs.crawleo.dev/api-reference/endpoint/google-maps.md" },
+        { "path": ".gsd/research/crawleo-docs/md/overview.md", "url": "https://docs.crawleo.dev/mcp/overview.md" },
+        { "path": ".gsd/research/crawleo-docs/openapi.json.json", "url": "https://docs.crawleo.dev/openapi.json" }
+      ],
+      "cost": "Endpoint doc: 30 credits per request. MCP overview: 10 credits per request. Preserve as source conflict.",
+      "parameters": [
+        { "in": "header", "name": "x-api-key", "type": "string", "required": true, "default": null, "limits_or_enum": null, "description": "Crawleo API key; Authorization Bearer is documented as an alternative." },
+        { "in": "query", "name": "q", "type": "string", "required": true, "default": null, "limits_or_enum": null, "description": "Business name, landmark, address, keyword, or category + location query." },
+        { "in": "query", "name": "hl", "type": "string", "required": false, "default": "not specified in Crawleo docs", "limits_or_enum": "ISO 639-1 examples: en, ar, fr, de", "description": "Language code for returned text." },
+        { "in": "query", "name": "ll", "type": "string", "required": false, "default": null, "limits_or_enum": "format @latitude,longitude,zoomz; zoom 1z-21z", "description": "Location bias." },
+        { "in": "query", "name": "placeId", "type": "string", "required": false, "default": null, "limits_or_enum": null, "description": "Google Place ID for exact place lookup." },
+        { "in": "query", "name": "cid", "type": "string", "required": false, "default": null, "limits_or_enum": null, "description": "Google numeric business/customer ID for exact business lookup." }
+      ],
+      "parameter_combinations": ["q", "q + hl", "q + ll", "q + ll + hl", "q + placeId", "q + placeId + hl", "q + cid", "q + cid + hl"],
+      "examples": [
+        { "label": "Basic Maps search", "request": "GET /google-maps?q=restaurants%20in%20Paris&hl=fr" },
+        { "label": "Location-biased search", "request": "GET /google-maps?q=coffee%20shops&ll=%4048.8566%2C2.3522%2C15z&hl=fr" },
+        { "label": "Place lookup", "request": "GET /google-maps?q=Le%20Comptoir&placeId=ChIJLU7jZClu5kcR4PcOOO6p3I0" }
+      ],
+      "response_shape": {
+        "top_level_fields": ["parameters", "google_maps_results", "credits"],
+        "result_fields": ["position", "title", "address", "rating", "ratingCount", "phoneNumber", "website", "type", "types", "priceLevel", "placeId", "cid", "latitude", "longitude", "openingHours", "thumbnailUrl"]
+      },
+      "errors": [
+        { "status": 400, "description": "Missing required query parameter `q`" },
+        { "status": 401, "description": "Invalid or missing API key" },
+        { "status": 403, "description": "Inactive account or expired subscription" },
+        { "status": 429, "description": "Credits exhausted or concurrent request limit reached" },
+        { "status": 500, "description": "Internal server error" }
+      ],
+      "ambiguities": ["Google Maps cost differs between endpoint doc and MCP overview.", "Default for `hl` is not specified in Crawleo docs."]
+    },
+    {
+      "id": "crawl",
+      "name": "Crawler API",
+      "method": "GET",
+      "path": "/crawl",
+      "url": "https://api.crawleo.dev/crawl",
+      "mcp_tool": "crawl_web",
+      "description": "Direct URL crawling API with optional JavaScript rendering, content extraction, screenshots, and multiple output formats.",
+      "sources": [
+        { "path": ".gsd/research/crawleo-docs/md/crawler.md", "url": "https://docs.crawleo.dev/api-reference/endpoint/crawler.md" },
+        { "path": ".gsd/research/crawleo-docs/md/overview.md", "url": "https://docs.crawleo.dev/mcp/overview.md" },
+        { "path": ".gsd/research/crawleo-docs/openapi.json.json", "url": "https://docs.crawleo.dev/openapi.json" }
+      ],
+      "cost": "1 credit per URL when render_js=false; 10 credits per URL when render_js=true",
+      "parameters": [
+        { "in": "header", "name": "x-api-key", "type": "string", "required": true, "default": null, "limits_or_enum": null, "description": "Crawleo API key; Authorization Bearer is documented as an alternative." },
+        { "in": "query", "name": "urls", "type": "string", "required": true, "default": null, "limits_or_enum": "single URL or comma-separated URLs", "description": "URL or URLs to crawl." },
+        { "in": "query", "name": "render_js", "type": "boolean", "required": false, "default": false, "limits_or_enum": null, "description": "Enable browser rendering; changes cost from 1 to 10 credits per URL." },
+        { "in": "query", "name": "geolocation", "type": "string", "required": false, "default": null, "limits_or_enum": "ISO 3166-1 alpha-2 examples: us, gb, de", "description": "Country code for geolocation." },
+        { "in": "query", "name": "raw_html", "type": "boolean", "required": false, "default": false, "limits_or_enum": null, "description": "Return raw HTML." },
+        { "in": "query", "name": "enhanced_html", "type": "boolean", "required": false, "default": true, "limits_or_enum": null, "description": "Return cleaned/sanitized HTML." },
+        { "in": "query", "name": "page_text", "type": "boolean", "required": false, "default": false, "limits_or_enum": null, "description": "Return plain text extraction." },
+        { "in": "query", "name": "markdown", "type": "boolean", "required": false, "default": true, "limits_or_enum": null, "description": "Return Markdown conversion." },
+        { "in": "query", "name": "screenshot", "type": "boolean", "required": false, "default": false, "limits_or_enum": "only available when render_js=true", "description": "Capture screenshot." },
+        { "in": "query", "name": "screenshot_full_page", "type": "boolean", "required": false, "default": false, "limits_or_enum": "screenshot=true and render_js=true required for screenshot output", "description": "Capture full-page screenshot instead of viewport only." }
+      ],
+      "examples": [
+        { "label": "Basic crawl with Markdown", "request": "GET /crawl?urls=https://example.com&markdown=true" },
+        { "label": "Rendered crawl with screenshot", "request": "GET /crawl?urls=https://example.com&render_js=true&screenshot=true" }
+      ],
+      "response_shape": {
+        "top_level_fields": ["results", "credits", "successful_pages"],
+        "result_fields": ["url", "status_code", "raw_html", "enhanced_html", "markdown", "page_text", "screenshot", "error"]
+      },
+      "errors": "not specified in Crawleo docs",
+      "ambiguities": ["Crawler endpoint error response table is not specified in Crawleo docs."]
+    },
+    {
+      "id": "headful_browser",
+      "name": "Headful Browser API",
+      "method": "GET",
+      "path": "/headful-browser",
+      "url": "https://api.crawleo.dev/headful-browser",
+      "mcp_tool": "headful_browser",
+      "description": "Premium headed browser crawling with anti-bot evasion, SOAX residential proxies, screenshots, and multiple output formats.",
+      "sources": [
+        { "path": ".gsd/research/crawleo-docs/md/headful-browser.md", "url": "https://docs.crawleo.dev/api-reference/endpoint/headful-browser.md" },
+        { "path": ".gsd/research/crawleo-docs/md/overview.md", "url": "https://docs.crawleo.dev/mcp/overview.md" }
+      ],
+      "cost": "50 credits per URL; failed requests cost 0 credits",
+      "parameters": [
+        { "in": "header", "name": "x-api-key", "type": "string", "required": true, "default": null, "limits_or_enum": null, "description": "Crawleo API key; Authorization Bearer is documented as an alternative." },
+        { "in": "query", "name": "urls", "type": "string", "required": true, "default": null, "limits_or_enum": "single URL or comma-separated URLs", "description": "One or more URLs to crawl." },
+        { "in": "query", "name": "country", "type": "string", "required": false, "default": "us", "limits_or_enum": "examples: us, gb, de, fr, jp, in, br, ca, au, and more", "description": "Residential proxy geolocation country code." },
+        { "in": "query", "name": "output_format", "type": "string", "required": false, "default": "markdown", "limits_or_enum": ["markdown", "enhanced_html", "raw_html", "page_text"], "description": "Output format for crawled page content." },
+        { "in": "query", "name": "screenshot", "type": "boolean", "required": false, "default": false, "limits_or_enum": null, "description": "Capture full-page screenshot returned as URL." }
+      ],
+      "examples": [
+        { "label": "Basic headful crawl", "request": "GET /headful-browser?urls=https://example.com&output_format=markdown" },
+        { "label": "Headful crawl with screenshot", "request": "GET /headful-browser?urls=https://example.com&screenshot=true" }
+      ],
+      "response_shape": {
+        "top_level_fields": ["status", "data", "credits_used", "credits_remaining"],
+        "result_fields": ["url", "markdown", "raw_html", "enhanced_html", "page_text", "screenshot", "blocked"]
+      },
+      "errors": "not specified in Crawleo docs",
+      "ambiguities": [
+        "Headful Browser is documented in endpoint-specific docs and docs index but absent from the local OpenAPI snapshot.",
+        "Headful Browser endpoint error response table is not specified in Crawleo docs."
+      ]
+    }
+  ]
+}

package/contracts/crawleo-endpoints.md

@@ -0,0 +1,268 @@
+# Crawleo Endpoint Contract Inventory
+
+This contract inventory is the S01 handoff artifact for downstream implementation and documentation. It is source-backed by Crawleo endpoint-specific docs, the Crawleo MCP overview, the Crawleo docs index, authentication docs, and the local OpenAPI snapshot.
+
+## Contract Rules
+
+- Base REST URL: `https://api.crawleo.dev`
+- Primary authentication: `CRAWLEO_API_KEY` sent as `x-api-key`.
+- Alternate authentication documented by Crawleo: `Authorization: Bearer YOUR_API_KEY`.
+- Never print, log, echo, or persist API key values.
+- Endpoint-specific Crawleo docs are authoritative where the local OpenAPI snapshot is narrower.
+- Missing defaults, ranges, error tables, or unclear example-only fields must say: `not specified in Crawleo docs`.
+- Default verification must not call Crawleo or consume credits.
+
+## Source Conflict Summary
+
+- Endpoint docs and docs index cover `/search`, `/google-search`, `/google-maps`, `/crawl`, and `/headful-browser`.
+- Local OpenAPI snapshot covers only `/search`, `/google-maps`, and `/crawl`.
+- `/google-search` and `/headful-browser` remain in scope because Crawleo endpoint docs and docs index document them.
+- Google Maps cost conflicts by source: endpoint doc says 30 credits per request; MCP overview says 10 credits per request.
+- `/search` examples include `count=10`, but the visible parameter table does not list `count`; treat `count` as example-only/ambiguous until verified.
+
+## MCP Mapping
+
+MCP endpoint: `https://api.crawleo.dev/mcp`
+
+| MCP Tool | REST Endpoint | Documented Cost |
+|---|---|---|
+| `search_web` | `/search` | 10 credits per page of results |
+| `google_search` | `/google-search` | 10 credits per request |
+| `google_maps` | `/google-maps` | 10 credits per request in MCP overview; conflicts with endpoint doc cost of 30 credits per request |
+| `crawl_web` | `/crawl` | 1 credit per URL for HTTP request; 10 credits per URL for browser rendering |
+| `headful_browser` | `/headful-browser` | 50 credits per URL |
+
+## Endpoint Contracts
+
+### `/search` — Bing Search API
+
+- Method: `GET`
+- URL: `https://api.crawleo.dev/search`
+- MCP tool: `search_web`
+- Purpose: Bing-powered real-time web search with optional auto-crawling and content extraction for LLM/RAG workflows.
+- Sources:
+  - `.gsd/research/crawleo-docs/md/search.md` / `https://docs.crawleo.dev/api-reference/endpoint/search.md`
+  - `.gsd/research/crawleo-docs/md/overview.md` / `https://docs.crawleo.dev/mcp/overview.md`
+  - `.gsd/research/crawleo-docs/openapi.json.json` / `https://docs.crawleo.dev/openapi.json`
+- Cost: 10 credits per page via `max_pages` / MCP `search_web` cost. Exact cost behavior for example-only `count` is `not specified in Crawleo docs`.
+
+#### Parameters
+
+| Location | Name | Type | Required | Default | Limits / Enum | Notes |
+|---|---|---:|---:|---|---|---|
+| header | `x-api-key` | string | yes | — | — | Crawleo API key; Bearer auth is also documented. |
+| query | `query` | string | yes | — | — | Search query string. |
+| query | `max_pages` | integer | no | `1` | `not specified in Crawleo docs` | Maximum pages to fetch; each page costs 10 credits. |
+| query | `setLang` | string | no | — | examples: `en`, `es`, `fr`, `de` | Language code. |
+| query | `cc` | string | no | — | examples: `US`, `GB`, `DE` | Country code. |
+| query | `geolocation` | string | no | — | `random` documented | Geographic location. |
+| query | `device` | string | no | `desktop` | `desktop`, `mobile`, `tablet` | Device simulation. |
+| query | `copilot_answer` | boolean | no | `true` | — | Include Copilot answers. |
+| query | `questions_answers` | boolean | no | `true` | — | Include People Also Ask. |
+| query | `related_queries` | boolean | no | `true` | — | Include related searches. |
+| query | `sidebar` | boolean | no | `true` | — | Include sidebar data. |
+| query | `direct_answer` | boolean | no | `true` | — | Include direct answers. |
+| query | `raw_html` | boolean | no | `false` | — | Return raw HTML. |
+| query | `enhanced_html` | boolean | no | `false` | — | Return cleaned HTML. |
+| query | `page_text` | boolean | no | `false` | — | Return plain text. |
+| query | `markdown` | boolean | no | `false` | — | Return Markdown. |
+| query | `auto_crawling` | boolean | no | `false` | — | Crawl result URLs automatically. |
+| query | `count` | integer | no | `not specified in Crawleo docs` | `not specified in Crawleo docs` | Appears in examples but not in visible parameter table. |
+
+#### Examples
+
+- `GET /search?query=machine%20learning&count=10`
+- `GET /search?query=AI%20agents&auto_crawling=true&markdown=true`
+
+#### Response Shape
+
+Top-level fields include `query`, `pages_fetched`, `pages`, `total_results`, `search_results`, `related_queries`, and `credits`. Result/page fields include `title`, `link`, `date`, `snippet`, `source`, `page_content`, `enhanced_html`, and `page_markdown`.
+
+#### Errors / Ambiguities
+
+- Error response table: `not specified in Crawleo docs`.
+- `count` appears in examples but not the visible parameter table.
+
+### `/google-search` — Google Search API
+
+- Method: `GET`
+- URL: `https://api.crawleo.dev/google-search`
+- MCP tool: `google_search`
+- Purpose: Real-time Google SERP data including web, news, images, places, shopping, knowledge graph, People Also Ask, related searches, and answer boxes.
+- Sources:
+  - `.gsd/research/crawleo-docs/md/google-search.md` / `https://docs.crawleo.dev/api-reference/endpoint/google-search.md`
+  - `.gsd/research/crawleo-docs/md/overview.md` / `https://docs.crawleo.dev/mcp/overview.md`
+- Cost: 10 credits per request.
+
+#### Parameters
+
+| Location | Name | Type | Required | Default | Limits / Enum | Notes |
+|---|---|---:|---:|---|---|---|
+| header | `x-api-key` | string | yes | — | — | Crawleo API key; Bearer auth is also documented. |
+| query | `q` | string | yes | — | — | Search query. |
+| query | `gl` | string | no | `us` | ISO 3166-1 alpha-2 examples: `us`, `gb`, `eg`, `de`, `fr` | Country. |
+| query | `hl` | string | no | `en` | IETF language examples: `en`, `ar`, `fr`, `de` | Language. |
+| query | `tbs` | string | no | — | `qdr:h`, `qdr:d`, `qdr:w`, `qdr:m`, `qdr:y` | Freshness filter. |
+| query | `page` | integer | no | `1` | 1-indexed; upper bound `not specified in Crawleo docs` | Result page. |
+| query | `num` | integer | no | `10` | `1–100` | Results per page. |
+| query | `type` | string | no | `search` | `search`, `news`, `images`, `places`, `shopping` | Result vertical. |
+
+#### Examples
+
+- `GET /google-search?q=best%20CRM%20software&gl=us&hl=en&num=10`
+- `GET /google-search?q=AI&type=news&tbs=qdr:d`
+- `GET /google-search?q=coffee&type=places&gl=us`
+- `GET /google-search?q=laptop&type=shopping`
+
+#### Response Shape
+
+Top-level fields include `parameters`, `google_search_results`, `knowledgeGraph`, `peopleAlsoAsk`, `relatedSearches`, and `answerBox`. Result fields include `title`, `link`, `snippet`, and `position`.
+
+#### Errors / Ambiguities
+
+| Status | Meaning |
+|---:|---|
+| 400 | Missing required parameter `q` |
+| 401 | Invalid or missing API key |
+| 402 | Insufficient credits |
+| 429 | Rate limit exceeded |
+| 500 | Internal server error |
+
+- `/google-search` is absent from the local OpenAPI snapshot but present in endpoint-specific docs and docs index.
+
+### `/google-maps` — Google Maps API
+
+- Method: `GET`
+- URL: `https://api.crawleo.dev/google-maps`
+- MCP tool: `google_maps`
+- Purpose: Google Maps business/place/landmark search with structured place data.
+- Sources:
+  - `.gsd/research/crawleo-docs/md/google-maps.md` / `https://docs.crawleo.dev/api-reference/endpoint/google-maps.md`
+  - `.gsd/research/crawleo-docs/md/overview.md` / `https://docs.crawleo.dev/mcp/overview.md`
+  - `.gsd/research/crawleo-docs/openapi.json.json` / `https://docs.crawleo.dev/openapi.json`
+- Cost: endpoint doc says 30 credits per request; MCP overview says 10 credits per request.
+
+#### Parameters
+
+| Location | Name | Type | Required | Default | Limits / Enum | Notes |
+|---|---|---:|---:|---|---|---|
+| header | `x-api-key` | string | yes | — | — | Crawleo API key; Bearer auth is also documented. |
+| query | `q` | string | yes | — | — | Business name, landmark, address, keyword, or category + location query. |
+| query | `hl` | string | no | `not specified in Crawleo docs` | ISO 639-1 examples: `en`, `ar`, `fr`, `de` | Language code. |
+| query | `ll` | string | no | — | `@latitude,longitude,zoomz`, zoom `1z–21z` | Location bias. |
+| query | `placeId` | string | no | — | — | Google Place ID lookup. |
+| query | `cid` | string | no | — | — | Google numeric business/customer ID lookup. |
+
+Documented combinations: `q`, `q + hl`, `q + ll`, `q + ll + hl`, `q + placeId`, `q + placeId + hl`, `q + cid`, `q + cid + hl`.
+
+#### Examples
+
+- `GET /google-maps?q=restaurants%20in%20Paris&hl=fr`
+- `GET /google-maps?q=coffee%20shops&ll=%4048.8566%2C2.3522%2C15z&hl=fr`
+- `GET /google-maps?q=Le%20Comptoir&placeId=ChIJLU7jZClu5kcR4PcOOO6p3I0`
+
+#### Response Shape
+
+Top-level fields include `parameters`, `google_maps_results`, and `credits`. Place result fields include `position`, `title`, `address`, `rating`, `ratingCount`, `phoneNumber`, `website`, `type`, `types`, `priceLevel`, `placeId`, `cid`, `latitude`, `longitude`, `openingHours`, and `thumbnailUrl`.
+
+#### Errors / Ambiguities
+
+| Status | Meaning |
+|---:|---|
+| 400 | Missing required query parameter `q` |
+| 401 | Invalid or missing API key |
+| 403 | Inactive account or expired subscription |
+| 429 | Credits exhausted or concurrent request limit reached |
+| 500 | Internal server error |
+
+- Cost conflict: endpoint doc says 30 credits per request; MCP overview says 10 credits per request.
+- Default for `hl` is `not specified in Crawleo docs`.
+
+### `/crawl` — Crawler API
+
+- Method: `GET`
+- URL: `https://api.crawleo.dev/crawl`
+- MCP tool: `crawl_web`
+- Purpose: Direct URL crawling with optional JavaScript rendering, extraction, screenshots, and multiple output formats.
+- Sources:
+  - `.gsd/research/crawleo-docs/md/crawler.md` / `https://docs.crawleo.dev/api-reference/endpoint/crawler.md`
+  - `.gsd/research/crawleo-docs/md/overview.md` / `https://docs.crawleo.dev/mcp/overview.md`
+  - `.gsd/research/crawleo-docs/openapi.json.json` / `https://docs.crawleo.dev/openapi.json`
+- Cost: 1 credit per URL when `render_js=false`; 10 credits per URL when `render_js=true`.
+
+#### Parameters
+
+| Location | Name | Type | Required | Default | Limits / Enum | Notes |
+|---|---|---:|---:|---|---|---|
+| header | `x-api-key` | string | yes | — | — | Crawleo API key; Bearer auth is also documented. |
+| query | `urls` | string | yes | — | single URL or comma-separated URLs | URL(s) to crawl. |
+| query | `render_js` | boolean | no | `false` | — | Browser rendering; increases cost to 10 credits per URL. |
+| query | `geolocation` | string | no | — | ISO 3166-1 alpha-2 examples: `us`, `gb`, `de` | Geolocation country. |
+| query | `raw_html` | boolean | no | `false` | — | Return raw HTML. |
+| query | `enhanced_html` | boolean | no | `true` | — | Return cleaned HTML. |
+| query | `page_text` | boolean | no | `false` | — | Return plain text. |
+| query | `markdown` | boolean | no | `true` | — | Return Markdown. |
+| query | `screenshot` | boolean | no | `false` | Only available when `render_js=true` | Capture screenshot. |
+| query | `screenshot_full_page` | boolean | no | `false` | Requires screenshot flow | Capture full page. |
+
+#### Examples
+
+- `GET /crawl?urls=https://example.com&markdown=true`
+- `GET /crawl?urls=https://example.com&render_js=true&screenshot=true`
+
+#### Response Shape
+
+Top-level fields include `results`, `credits`, and `successful_pages`. Per-result fields include `url`, `status_code`, `raw_html`, `enhanced_html`, `markdown`, `page_text`, `screenshot`, and `error`.
+
+#### Errors / Ambiguities
+
+- Error response table: `not specified in Crawleo docs`.
+
+### `/headful-browser` — Headful Browser API
+
+- Method: `GET`
+- URL: `https://api.crawleo.dev/headful-browser`
+- MCP tool: `headful_browser`
+- Purpose: Premium headed browser crawling with anti-bot evasion, SOAX residential proxies, screenshots, and multiple output formats.
+- Sources:
+  - `.gsd/research/crawleo-docs/md/headful-browser.md` / `https://docs.crawleo.dev/api-reference/endpoint/headful-browser.md`
+  - `.gsd/research/crawleo-docs/md/overview.md` / `https://docs.crawleo.dev/mcp/overview.md`
+- Cost: 50 credits per URL; failed requests cost 0 credits.
+
+#### Parameters
+
+| Location | Name | Type | Required | Default | Limits / Enum | Notes |
+|---|---|---:|---:|---|---|---|
+| header | `x-api-key` | string | yes | — | — | Crawleo API key; Bearer auth is also documented. |
+| query | `urls` | string | yes | — | single URL or comma-separated URLs | URL(s) to crawl. |
+| query | `country` | string | no | `us` | examples: `us`, `gb`, `de`, `fr`, `jp`, `in`, `br`, `ca`, `au`, and more | Residential proxy country. |
+| query | `output_format` | string | no | `markdown` | `markdown`, `enhanced_html`, `raw_html`, `page_text` | Output format. |
+| query | `screenshot` | boolean | no | `false` | — | Return screenshot URL. |
+
+#### Examples
+
+- `GET /headful-browser?urls=https://example.com&output_format=markdown`
+- `GET /headful-browser?urls=https://example.com&screenshot=true`
+
+#### Response Shape
+
+Top-level fields include `status`, `data`, `credits_used`, and `credits_remaining`. Per-item fields include `url`, `markdown`, `raw_html`, `enhanced_html`, `page_text`, `screenshot`, and `blocked`.
+
+#### Errors / Ambiguities
+
+- `/headful-browser` is absent from the local OpenAPI snapshot but present in endpoint-specific docs and docs index.
+- Error response table: `not specified in Crawleo docs`.
+
+## Verification
+
+Structured JSON should parse with:
+
+```bash
+node -e "JSON.parse(require('fs').readFileSync('contracts/crawleo-endpoints.json','utf8')); console.log('valid json')"
+```
+
+Full S01 contract verification will be added in `scripts/verify-contracts.js` and run with:
+
+```bash
+node scripts/verify-contracts.js
+```

package/contracts/final-assembly-report.md

@@ -0,0 +1,84 @@
+# Crawleo OpenClaw Skill Final Assembly Report
+
+This report summarizes the final package assembly state for the Crawleo OpenClaw skill milestone.
+
+## Package Contents
+
+The package includes:
+
+- Package metadata and scripts in `package.json`.
+- OpenClaw-facing metadata in `skill.json`.
+- OpenClaw-facing instructions in `SKILL.md`.
+- User-facing setup, usage, error, and verification docs in `README.md`.
+- Crawleo endpoint contracts in `contracts/crawleo-endpoints.json` and `contracts/crawleo-endpoints.md`.
+- Endpoint-to-wrapper/test/example coverage in `contracts/coverage-checklist.md`.
+- REST wrapper implementation in `src/index.js`, `src/client.js`, `src/contract.js`, `src/endpoints.js`, and `src/errors.js`.
+- Safe examples in `examples/offline-fake-fetch.js` and `examples/live-usage-template.js`.
+- Offline and live-gated tests in `test/`.
+- Verification scripts in `scripts/verify-contracts.js`, `scripts/verify-scaffold.js`, and `scripts/verify-final.js`.
+
+## Endpoint and Tool Coverage
+
+| REST Endpoint | MCP Tool | Wrapper Method | Verification Surface |
+|---|---|---|---|
+| `/search` | `search_web` | `client.search` | Contract, README, examples, wrapper fixtures, error fixtures, final verifier |
+| `/google-search` | `google_search` | `client.googleSearch` | Contract, README, examples, wrapper fixtures, final verifier |
+| `/google-maps` | `google_maps` | `client.googleMaps` | Contract, README, examples, wrapper fixtures, final verifier |
+| `/crawl` | `crawl_web` | `client.crawl` | Contract, README, examples, wrapper fixtures, final verifier |
+| `/headful-browser` | `headful_browser` | `client.headfulBrowser` | Contract, README, examples, wrapper fixtures, final verifier |
+
+Coverage is grounded in Crawleo endpoint-specific documentation. Where Crawleo sources are ambiguous or conflict, the contract preserves the ambiguity instead of inventing behavior; unresolved values use `not specified in Crawleo docs`.
+
+## Verification Commands
+
+Default verification is offline and safe by default:
+
+```bash
+npm test
+npm run verify:contracts
+npm run verify:examples
+npm run verify:scaffold
+npm run verify:final
+```
+
+In this environment, the default npm cache path is on a full C: drive. Use `npm_config_cache=.npm-cache` before npm commands if npm reports `ENOSPC` while writing cache or logs.
+
+Latest final verification evidence used:
+
+```bash
+npm_config_cache=.npm-cache npm test \
+  && npm_config_cache=.npm-cache npm run test:live \
+  && npm_config_cache=.npm-cache npm run verify:contracts \
+  && npm_config_cache=.npm-cache npm run verify:examples \
+  && npm_config_cache=.npm-cache npm run verify:scaffold \
+  && npm_config_cache=.npm-cache npm run verify:final
+```
+
+Result: 35 passing tests, 1 skipped live test, explicit `test:live` skipped safely, contract verification passed, examples verification passed with live skip, scaffold verification passed, and final assembly verification passed.
+
+## Live-Test Gate Status
+
+Live Crawleo calls are not part of default verification.
+
+Optional live smoke tests require both:
+
+1. `CRAWLEO_API_KEY`
+2. `CRAWLEO_ENABLE_LIVE_TESTS=1`
+
+Run optional live verification with:
+
+```bash
+CRAWLEO_API_KEY=... CRAWLEO_ENABLE_LIVE_TESTS=1 npm run test:live
+```
+
+Without both variables, `npm run test:live` exits successfully with the live smoke test skipped. The live usage example uses a separate explicit gate, `CRAWLEO_ENABLE_LIVE_EXAMPLE=1`, and also skips safely without credentials.
+
+## Known Limitations
+
+- No live Crawleo API call was executed during default milestone verification because credentials and explicit live enablement were not provided.
+- Crawleo source ambiguity is intentionally preserved, including `/search` example-only `count`, Google Maps cost conflict, and OpenAPI omissions for `/google-search` and `/headful-browser`.
+- Final verification is file/content based and offline; it proves package assembly and wrapper behavior through injected-fetch tests rather than live Crawleo availability.
+
+## Final Assembly Verdict
+
+The package is assembled as a Crawleo-branded OpenClaw skill with complete documented endpoint coverage, offline-safe REST wrappers, safe examples, stable error diagnostics, live-test gating, and reproducible offline verification.

package/examples/README.md

@@ -0,0 +1,37 @@
+# Crawleo OpenClaw Skill Examples
+
+These examples show how to use the Crawleo wrapper API safely.
+
+## Offline fake-fetch example
+
+```bash
+node examples/offline-fake-fetch.js
+```
+
+This example injects a fake `fetch` implementation and calls every wrapper method without network access, `CRAWLEO_API_KEY`, or Crawleo credit usage.
+
+Covered methods:
+
+- `client.search`
+- `client.googleSearch`
+- `client.googleMaps`
+- `client.crawl`
+- `client.headfulBrowser`
+
+## Live usage template
+
+```bash
+CRAWLEO_API_KEY=... CRAWLEO_ENABLE_LIVE_EXAMPLE=1 node examples/live-usage-template.js
+```
+
+The live template exits successfully without making a request unless both `CRAWLEO_API_KEY` and `CRAWLEO_ENABLE_LIVE_EXAMPLE=1` are present. Never print or commit API key values.
+
+Default verification should use the offline example only or rely on the template's safe skip behavior.
+
+Optional live tests use the same two-part gate:
+
+```bash
+CRAWLEO_API_KEY=... CRAWLEO_ENABLE_LIVE_TESTS=1 npm run test:live
+```
+
+Without both variables, the live test file skips safely and exits 0.