High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.
chore: removing file and improving gitignore
Luigi Agosti0122a633cf84
diff --git a/.gitignore b/.gitignoreindex 5e36bf16..aadd7b2f 100644--- a/.gitignore+++ b/.gitignore@@ -43,3 +43,4 @@ debug.logpinchtab.exe.gocache+.DS_Store\ No newline at end of filediff --git a/docs/references/api-reference.json b/docs/references/api-reference.jsondeleted file mode 100644index c6dd251e..00000000--- a/docs/references/api-reference.json+++ /dev/null@@ -1,666 +0,0 @@-{- "version": "2.0",- "generated": "auto-merged from code + user metadata",- "count": 60,- "endpoints": [- {- "method": "GET",- "path": "/",- "handler": "",- "description": "Dashboard UI (root)",- "curl": true,- "examples": {},- "html": true- },- {- "method": "GET",- "path": "/cookies",- "handler": "HandleGetCookies",- "description": "Manage cookies",- "curl": true,- "examples": {}- },- {- "method": "GET",- "path": "/dashboard",- "handler": "",- "description": "Dashboard page",- "curl": true,- "examples": {},- "html": true- },- {- "method": "GET",- "path": "/dashboard/",- "handler": "",- "description": "Dashboard resources",- "curl": true,- "examples": {},- "html": true- },- {- "method": "GET",- "path": "/dashboard/agents",- "handler": "handleAgents",- "description": "Agent activity feed",- "curl": true,- "examples": {}- },- {- "method": "GET",- "path": "/dashboard/events",- "handler": "handleSSE",- "description": "Event stream",- "curl": true,- "examples": {}- },- {- "method": "GET",- "path": "/download",- "handler": "HandleDownload",- "description": "Download resource",- "curl": true,- "examples": {}- },- {- "method": "GET",- "path": "/health",- "handler": "HandleHealth",- "description": "Health check",- "cli": true,- "curl": true,- "examples": {}- },- {- "method": "GET",- "path": "/instances",- "handler": "handleList",- "description": "List instances",- "cli": true,- "curl": true,- "examples": {},- "tldr": "List all running Chrome instances",- "cliExample": "pinchtab instances",- "curlExample": "curl http://localhost:9867/instances",- "parameters": "None",- "payload": "N/A (GET request)",- "defaults": "Returns array of instances with id, profileName, port, headless, status"- },- {- "method": "GET",- "path": "/instances/tabs",- "handler": "handleAllTabs",- "description": "List tabs across instances",- "curl": true,- "examples": {},- "tldr": "List all tabs across all instances",- "cli": false,- "curlExample": "curl http://localhost:9867/instances/tabs",- "parameters": "None",- "payload": "N/A (GET request)"- },- {- "method": "GET",- "path": "/instances/{id}/logs",- "handler": "handleLogsByID",- "description": "Instance logs",- "curl": true,- "examples": {},- "tldr": "Get instance logs",- "cli": false,- "curlExample": "curl \"http://localhost:9867/instances/inst_abc123/logs?limit=100\"",- "parameters": "limit (int, query, optional, default: 100)",- "payload": "N/A (GET request)"- },- {- "method": "GET",- "path": "/instances/{id}/proxy/screencast",- "handler": "handleProxyScreencast",- "description": "Proxy screencast",- "curl": true,- "examples": {},- "tldr": "Proxy screencast stream from instance",- "cli": false,- "curlExample": "curl \"http://localhost:9867/instances/inst_abc123/proxy/screencast?tabId=tab-1\"",- "parameters": "tabId (string, query, required)",- "payload": "N/A (GET request)"- },- {- "method": "GET",- "path": "/instances/{id}/screencast",- "handler": "proxyToInstance",- "description": "/instances/{id}/screencast endpoint",- "curl": true,- "examples": {},- "tldr": "Stream screen from instance tab",- "cli": false,- "curlExample": "curl \"http://localhost:9867/instances/inst_abc123/screencast?tabId=tab-1\"",- "parameters": "tabId (string, query, required), format (string, optional, default: \"webm\")",- "payload": "N/A (GET request)"- },- {- "method": "GET",- "path": "/screencast",- "handler": "HandleScreencast",- "description": "Stream screen",- "curl": true,- "examples": {}- },- {- "method": "GET",- "path": "/screencast/tabs",- "handler": "HandleScreencastAll",- "description": "List screencasts",- "curl": true,- "examples": {}- },- {- "method": "GET",- "path": "/screenshot",- "handler": "HandleScreenshot",- "description": "Take screenshot",- "cli": true,- "curl": true,- "examples": {}- },- {- "method": "GET",- "path": "/snapshot",- "handler": "HandleSnapshot",- "description": "Get accessibility tree",- "cli": true,- "curl": true,- "examples": {}- },- {- "method": "GET",- "path": "/stealth/status",- "handler": "HandleStealthStatus",- "description": "Get stealth status",- "curl": true,- "examples": {}- },- {- "method": "GET",- "path": "/tabs",- "handler": "HandleTabs",- "description": "List tabs",- "cli": true,- "curl": true,- "examples": {}- },- {- "method": "GET",- "path": "/text",- "handler": "HandleText",- "description": "Extract text",- "cli": true,- "curl": true,- "examples": {}- },- {- "method": "GET",- "path": "/welcome",- "handler": "",- "description": "Welcome page",- "curl": true,- "examples": {},- "html": true- },- {- "method": "POST",- "path": "/action",- "handler": "HandleAction",- "description": "Perform action (click, type, fill)",- "cli": true,- "curl": true,- "examples": {}- },- {- "method": "POST",- "path": "/actions",- "handler": "HandleActions",- "description": "Perform multiple actions",- "curl": true,- "examples": {}- },- {- "method": "POST",- "path": "/cookies",- "handler": "HandleSetCookies",- "description": "Manage cookies",- "curl": true,- "examples": {}- },- {- "method": "POST",- "path": "/evaluate",- "handler": "HandleEvaluate",- "description": "Execute JavaScript",- "cli": true,- "curl": true,- "examples": {}- },- {- "method": "POST",- "path": "/fingerprint/rotate",- "handler": "HandleFingerprintRotate",- "description": "Rotate browser fingerprint",- "curl": true,- "examples": {}- },- {- "method": "POST",- "path": "/instances/{id}/start",- "handler": "handleStartByInstanceID",- "description": "Start instance browser if not running",- "curl": true,- "examples": {},- "tldr": "Start or re-start browser for an existing instance",- "cli": false,- "curlExample": "curl -X POST http://localhost:9867/instances/inst_abc123/start",- "parameters": "id (string, path, required): Instance ID",- "payload": "N/A"- },- {- "method": "POST",- "path": "/instances/{id}/stop",- "handler": "handleStopByInstanceID",- "description": "Stop instance",- "curl": true,- "examples": {},- "tldr": "Stop/shutdown an instance",- "cli": false,- "curlExample": "curl -X POST http://localhost:9867/instances/inst_abc123/stop",- "parameters": "id (string, path, required): Instance ID",- "payload": "N/A"- },- {- "method": "POST",- "path": "/navigate",- "handler": "HandleNavigate",- "description": "Navigate to URL",- "cli": true,- "curl": true,- "examples": {}- },- {- "method": "POST",- "path": "/tab",- "handler": "HandleTab",- "description": "Create/manage tab",- "cli": true,- "curl": true,- "examples": {}- },- {- "method": "POST",- "path": "/tab/lock",- "handler": "HandleTabLock",- "description": "Lock tab",- "curl": true,- "examples": {}- },- {- "method": "POST",- "path": "/tab/unlock",- "handler": "HandleTabUnlock",- "description": "Unlock tab",- "curl": true,- "examples": {}- },- {- "method": "POST",- "path": "/upload",- "handler": "HandleUpload",- "description": "Upload file",- "curl": true,- "examples": {}- },- {- "method": "GET",- "path": "/profiles",- "handler": "handleList",- "description": "List all profiles",- "cli": true,- "curl": true,- "tldr": "List all browser profiles",- "cliExample": "pinchtab profiles",- "curlExample": "curl http://localhost:9867/profiles",- "curlExampleOutput": "[{\"id\":\"278be873adeb\",\"name\":\"Pinchtab org\",\"created\":\"2026-02-27T20:37:13.599055326Z\",\"diskUsage\":534952089,\"source\":\"created\"}]",- "parameters": "all (boolean, query, optional, default: false): Include temporary profiles",- "payload": "N/A (GET request)",- "defaults": "Returns array of profiles with id, name, created, diskUsage, source, etc.",- "examples": {}- },- {- "method": "POST",- "path": "/profiles",- "handler": "handleCreate",- "description": "Create a new profile",- "cli": true,- "curl": true,- "tldr": "Create a new browser profile",- "cliExample": "pinchtab profile create my-profile",- "curlExample": "curl -X POST http://localhost:9867/profiles -H \"Content-Type: application/json\" -d '{\"name\":\"my-profile\",\"description\":\"For testing\"}'",- "curlExampleOutput": "{\"status\":\"created\",\"id\":\"prof_278be87\",\"name\":\"my-profile\"}",- "parameters": "name (string, body, required): Profile name; description (string, body, optional); useWhen (string, body, optional)",- "payload": "{\"name\":\"my-profile\",\"description\":\"For web scraping\",\"useWhen\":\"Production scraping tasks\"}",- "defaults": "Returns profile ID (prof_XXXXXXXX), name, and status",- "examples": {}- },- {- "method": "GET",- "path": "/profiles/{id}",- "handler": "handleGetByID",- "description": "Get a specific profile",- "cli": false,- "curl": true,- "tldr": "Get profile info by ID or name",- "curlExample": "curl http://localhost:9867/profiles/prof_278be87",- "curlExampleOutput": "{\"id\":\"prof_278be87\",\"name\":\"Pinchtab org\",\"created\":\"2026-02-27T20:37:13.599055326Z\",\"diskUsage\":534952089,\"source\":\"created\",\"useWhen\":\"Gmail org\"}",- "parameters": "id (string, path, required): Profile ID or name",- "payload": "N/A (GET request)",- "defaults": "Supports both profile ID (hash) and profile name for backward compatibility",- "examples": {}- },- {- "method": "DELETE",- "path": "/profiles/{id}",- "handler": "handleDeleteByID",- "description": "Delete a profile",- "cli": true,- "curl": true,- "tldr": "Delete a browser profile",- "cliExample": "pinchtab profile delete my-profile",- "curlExample": "curl -X DELETE http://localhost:9867/profiles/prof_278be87",- "curlExampleOutput": "{\"status\":\"deleted\",\"id\":\"prof_278be87\",\"name\":\"Pinchtab org\"}",- "parameters": "id (string, path, required): Profile ID or name",- "payload": "N/A (DELETE request)",- "defaults": "Recursively deletes profile directory",- "examples": {}- },- {- "method": "PATCH",- "path": "/profiles/{id}",- "handler": "handleUpdateByIDOrName",- "description": "Update profile metadata",- "cli": false,- "curl": true,- "tldr": "Update profile description or useWhen",- "curlExample": "curl -X PATCH http://localhost:9867/profiles/prof_278be87 -H \"Content-Type: application/json\" -d '{\"description\":\"Updated description\",\"useWhen\":\"New use case\"}'",- "curlExampleOutput": "{\"status\":\"updated\",\"id\":\"prof_278be87\",\"name\":\"Pinchtab org\"}",- "parameters": "id (string, path, required): Profile ID or name; description (string, body, optional); useWhen (string, body, optional)",- "payload": "{\"description\":\"For production scraping\",\"useWhen\":\"When extracting data from e-commerce sites\"}",- "defaults": "Only provided fields are updated",- "examples": {}- },- {- "method": "POST",- "path": "/profiles/{id}/reset",- "handler": "handleResetByIDOrName",- "description": "Reset profile cache",- "cli": false,- "curl": true,- "tldr": "Clear browser cache, cookies, and session data",- "curlExample": "curl -X POST http://localhost:9867/profiles/prof_278be87/reset",- "curlExampleOutput": "{\"status\":\"reset\",\"id\":\"prof_278be87\",\"name\":\"Pinchtab org\"}",- "parameters": "id (string, path, required): Profile ID or name",- "payload": "N/A (POST with no body)",- "defaults": "Clears Sessions, Cache, Cookies, History, etc.",- "examples": {}- },- {- "method": "GET",- "path": "/profiles/{id}/logs",- "handler": "handleLogsByIDOrName",- "description": "Get profile activity logs",- "cli": false,- "curl": true,- "tldr": "View actions performed with this profile",- "curlExample": "curl \"http://localhost:9867/profiles/prof_278be87/logs?limit=50\"",- "curlExampleOutput": "[{\"timestamp\":\"2026-03-01T05:12:45Z\",\"action\":\"navigate\",\"url\":\"https://pinchtab.com\"},{\"timestamp\":\"2026-03-01T05:12:50Z\",\"action\":\"click\",\"selector\":\"e5\"}]",- "parameters": "id (string, path, required): Profile ID or name; limit (int, query, optional, default: 100)",- "payload": "N/A (GET request)",- "defaults": "Returns array of ActionRecord",- "examples": {}- },- {- "method": "GET",- "path": "/profiles/{id}/analytics",- "handler": "handleAnalyticsByIDOrName",- "description": "Get profile analytics",- "cli": false,- "curl": true,- "tldr": "View usage statistics and analytics",- "curlExample": "curl http://localhost:9867/profiles/prof_278be87/analytics",- "curlExampleOutput": "{\"totalActions\":256,\"averageActionDuration\":2.5,\"topActions\":{\"navigate\":128,\"click\":98,\"type\":30},\"lastUsed\":\"2026-03-01T05:12:50Z\"}",- "parameters": "id (string, path, required): Profile ID or name",- "payload": "N/A (GET request)",- "defaults": "Returns AnalyticsReport with usage statistics",- "examples": {}- },- {- "method": "POST",- "path": "/profiles/import",- "handler": "handleImport",- "description": "Import Chrome profile",- "cli": false,- "curl": true,- "tldr": "Import existing Chrome profile",- "curlExample": "curl -X POST http://localhost:9867/profiles/import -H \"Content-Type: application/json\" -d '{\"name\":\"imported\",\"sourcePath\":\"/Users/you/Library/Application Support/Google/Chrome/Default\"}'",- "curlExampleOutput": "{\"status\":\"imported\",\"name\":\"imported\"}",- "parameters": "name (string, body, required): Profile name; sourcePath (string, body, required): Path to Chrome user data dir; description (string, body, optional); useWhen (string, body, optional)",- "payload": "{\"name\":\"chrome-work\",\"sourcePath\":\"/path/to/chrome/profile\",\"description\":\"Imported from Chrome\"}",- "defaults": "Copies Chrome profile directory to ~/.pinchtab/profiles/",- "examples": {}- },- {- "method": "POST",- "path": "/tabs/{id}/navigate",- "handler": "proxyToTab",- "description": "Navigate tab to URL",- "tldr": "Navigate tab to URL",- "cli": true,- "curl": true,- "cliExample": "pinchtab tab navigate <tabId> https://pinchtab.com",- "curlExample": "curl -X POST http://localhost:9867/tabs/tab_abc/navigate -d '{\"url\":\"https://pinchtab.com\",\"timeout\":30}'",- "parameters": "url (string, body, required); timeout (int, optional); blockImages (bool, optional); blockAds (bool, optional)",- "payload": "{\"url\":\"https://pinchtab.com\",\"timeout\":30}",- "defaults": "timeout=30s; returns {url, title, status}"- },- {- "method": "GET",- "path": "/tabs/{id}/snapshot",- "handler": "proxyToTab",- "description": "Get page snapshot/structure tree",- "tldr": "Get page structure",- "cli": true,- "curl": true,- "cliExample": "pinchtab tab snapshot <tabId> -i -c",- "curlExample": "curl 'http://localhost:9867/tabs/tab_abc/snapshot?interactive=true&compact=true'",- "parameters": "interactive (bool, query, optional); compact (bool, query, optional); diff (bool, query, optional); depth (int, query, optional); maxTokens (int, query, optional)",- "payload": "N/A (GET)",- "defaults": "returns {elements: [], tree: {...}, meta: {...}}"- },- {- "method": "GET",- "path": "/tabs/{id}/screenshot",- "handler": "proxyToTab",- "description": "Take screenshot of tab",- "tldr": "Take screenshot",- "cli": true,- "curl": true,- "cliExample": "pinchtab tab screenshot <tabId> -o screenshot.png -q 85",- "curlExample": "curl 'http://localhost:9867/tabs/tab_abc/screenshot?quality=85' > screenshot.png",- "parameters": "format (string, query, optional: 'png' or 'jpeg'); quality (int, query, optional, 1-100)",- "payload": "N/A (GET)",- "defaults": "format=png; returns binary image data"- },- {- "method": "POST",- "path": "/tabs/{id}/action",- "handler": "proxyToTab",- "description": "Execute single action on tab",- "tldr": "Execute action",- "cli": true,- "curl": true,- "cliExample": "pinchtab tab click <tabId> e5",- "curlExample": "curl -X POST http://localhost:9867/tabs/tab_abc/action -d '{\"kind\":\"click\",\"ref\":\"e5\"}'",- "parameters": "kind (string, body, required: click|type|press|fill|hover|scroll|select|focus); ref (string, conditional); text (string, conditional); key (string, conditional)",- "payload": "{\"kind\":\"click\",\"ref\":\"e5\"}",- "defaults": "returns {kind, result, error}"- },- {- "method": "POST",- "path": "/tabs/{id}/actions",- "handler": "proxyToTab",- "description": "Execute multiple actions on tab",- "tldr": "Execute multiple actions",- "cli": true,- "curl": true,- "cliExample": "pinchtab tab actions <tabId> --json '[{\"kind\":\"click\",\"ref\":\"e5\"}]'",- "curlExample": "curl -X POST http://localhost:9867/tabs/tab_abc/actions -d '{\"actions\":[{\"kind\":\"click\",\"ref\":\"e5\"},{\"kind\":\"type\",\"ref\":\"e12\",\"text\":\"hello\"}]}'",- "parameters": "actions (array, body, required): array of action objects",- "payload": "{\"actions\":[{\"kind\":\"click\",\"ref\":\"e5\"},{\"kind\":\"type\",\"ref\":\"e12\",\"text\":\"hello\"}]}",- "defaults": "returns {results: [...]}"- },- {- "method": "GET",- "path": "/tabs/{id}/text",- "handler": "proxyToTab",- "description": "Extract visible text from tab",- "tldr": "Get page text",- "cli": true,- "curl": true,- "cliExample": "pinchtab tab text <tabId>",- "curlExample": "curl 'http://localhost:9867/tabs/tab_abc/text'",- "parameters": "raw (bool, query, optional): return raw innerText instead of structured",- "payload": "N/A (GET)",- "defaults": "returns {text: \"...\", elements: [...]}"- },- {- "method": "POST",- "path": "/tabs/{id}/evaluate",- "handler": "proxyToTab",- "description": "Evaluate JavaScript in tab",- "tldr": "Run JavaScript",- "cli": true,- "curl": true,- "cliExample": "pinchtab tab eval <tabId> 'document.title'",- "curlExample": "curl -X POST http://localhost:9867/tabs/tab_abc/evaluate -d '{\"expression\":\"document.title\"}'",- "parameters": "expression (string, body, required); await (bool, body, optional)",- "payload": "{\"expression\":\"document.querySelectorAll('a').length\"}",- "defaults": "returns {result: any, type: string}"- },- {- "method": "GET",- "path": "/tabs/{id}/pdf",- "handler": "proxyToTab",- "description": "Export tab as PDF",- "tldr": "Export as PDF",- "cli": true,- "curl": true,- "cliExample": "pinchtab tab pdf <tabId> -o output.pdf --landscape",- "curlExample": "curl 'http://localhost:9867/tabs/tab_abc/pdf?landscape=true&scale=1.0' > output.pdf",- "parameters": "landscape (bool, query, optional); scale (float, query, optional); margins (object, query, optional); pageRanges (string, query, optional)",- "payload": "N/A (GET)",- "defaults": "returns binary PDF data"- },- {- "method": "POST",- "path": "/tabs/{id}/pdf",- "handler": "proxyToTab",- "description": "Export tab as PDF (JSON body options)",- "tldr": "Export as PDF",- "cli": false,- "curl": true,- "curlExample": "curl -X POST 'http://localhost:9867/tabs/tab_abc/pdf?raw=true' -H 'Content-Type: application/json' -d '{\"landscape\":true,\"scale\":1.0}' > output.pdf",- "parameters": "same options as GET, but provided in JSON body",- "payload": "{\"landscape\":true,\"scale\":1.0,\"displayHeaderFooter\":true}",- "defaults": "returns binary PDF data (or JSON when output=file)"- },- {- "method": "GET",- "path": "/tabs/{id}/cookies",- "handler": "proxyToTab",- "description": "Get cookies for tab",- "tldr": "Get cookies",- "cli": true,- "curl": true,- "cliExample": "pinchtab tab cookies <tabId>",- "curlExample": "curl 'http://localhost:9867/tabs/tab_abc/cookies'",- "parameters": "none",- "payload": "N/A (GET)",- "defaults": "returns [{name, value, domain, path, ...}]"- },- {- "method": "POST",- "path": "/tabs/{id}/cookies",- "handler": "proxyToTab",- "description": "Set/delete cookies for tab",- "tldr": "Set cookies",- "cli": false,- "curl": true,- "curlExample": "curl -X POST http://localhost:9867/tabs/tab_abc/cookies -d '{\"action\":\"set\",\"cookies\":[{\"name\":\"key\",\"value\":\"val\"}]}'",- "parameters": "action (string, body, required: 'set' or 'delete'); cookies (array, body, required)",- "payload": "{\"action\":\"set\",\"cookies\":[{\"name\":\"session\",\"value\":\"abc123\",\"domain\":\".pinchtab.com\"}]}",- "defaults": "returns {set: [...], deleted: [...]}"- },- {- "method": "POST",- "path": "/tabs/{id}/lock",- "handler": "proxyToTab",- "description": "Lock tab for exclusive access",- "tldr": "Lock tab",- "cli": true,- "curl": true,- "cliExample": "pinchtab tab lock <tabId> --owner my-agent --ttl 60",- "curlExample": "curl -X POST http://localhost:9867/tabs/tab_abc/lock -d '{\"owner\":\"my-agent\",\"ttl\":60}'",- "parameters": "owner (string, body, required); ttl (int, body, required)",- "payload": "{\"owner\":\"agent-1\",\"ttl\":60}",- "defaults": "returns {locked: true, owner, expiresAt}"- },- {- "method": "POST",- "path": "/tabs/{id}/unlock",- "handler": "proxyToTab",- "description": "Unlock tab",- "tldr": "Unlock tab",- "cli": true,- "curl": true,- "cliExample": "pinchtab tab unlock <tabId> --owner my-agent",- "curlExample": "curl -X POST http://localhost:9867/tabs/tab_abc/unlock -d '{\"owner\":\"my-agent\"}'",- "parameters": "owner (string, body, required)",- "payload": "{\"owner\":\"agent-1\"}",- "defaults": "returns {unlocked: true}"- },- {- "method": "GET",- "path": "/tabs/{id}/locks",- "handler": "proxyToTab",- "description": "Check lock status",- "tldr": "Check lock status",- "cli": true,- "curl": true,- "cliExample": "pinchtab tab locks <tabId>",- "curlExample": "curl 'http://localhost:9867/tabs/tab_abc/locks'",- "parameters": "none",- "payload": "N/A (GET)",- "defaults": "returns {locked: bool, owner?, expiresAt?}"- },- {- "method": "POST",- "path": "/tabs/{id}/fingerprint/rotate",- "handler": "proxyToTab",- "description": "Rotate browser fingerprint",- "tldr": "Rotate fingerprint",- "cli": false,- "curl": true,- "curlExample": "curl -X POST http://localhost:9867/tabs/tab_abc/fingerprint/rotate",- "parameters": "none",- "payload": "N/A (POST, empty body)",- "defaults": "returns {rotated: true, userAgent, ...}"- }- ]-}