High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.
feat: add RESTful profile endpoints and improve API consistency
Mario71dfa1dd3ca5
diff --git a/docs/references/api-reference.json b/docs/references/api-reference.jsonindex 66975b33..2d007d54 100644--- a/docs/references/api-reference.json+++ b/docs/references/api-reference.json@@ -1,21 +1,8 @@{"version": "2.0","generated": "auto-merged from code + user metadata",- "count": 66,+ "count": 63,"endpoints": [- {- "method": "DELETE",- "path": "/profiles/{name}",- "handler": "handleDeleteByPath",- "description": "Manage profile",- "curl": true,- "examples": {},- "tldr": "Delete a profile",- "cli": false,- "curlExample": "curl -X DELETE http://localhost:9867/profiles/work",- "parameters": "name (string, path, required): Profile name",- "payload": "N/A"- },{"method": "GET","path": "/",@@ -251,59 +238,6 @@"curl": true,"examples": {}},- {- "method": "GET",- "path": "/profiles",- "handler": "handleList",- "description": "List profiles",- "cli": true,- "curl": true,- "examples": {},- "tldr": "List all browser profiles",- "cliExample": "pinchtab profiles",- "curlExample": "curl http://localhost:9867/profiles",- "parameters": "None",- "payload": "N/A (GET request)"- },- {- "method": "GET",- "path": "/profiles/{id}/instance",- "handler": "handleProfileInstance",- "description": "Get profile instance",- "curl": true,- "examples": {},- "tldr": "Get the current running instance for a profile",- "cli": false,- "curlExample": "curl \"http://localhost:9867/profiles/abc123/instance\"",- "parameters": "id (string, path, required): Profile ID",- "payload": "N/A (GET request)"- },- {- "method": "GET",- "path": "/profiles/{name}/analytics",- "handler": "handleAnalyticsByPath",- "description": "Profile analytics",- "curl": true,- "examples": {},- "tldr": "Get analytics/usage stats for a profile",- "cli": false,- "curlExample": "curl \"http://localhost:9867/profiles/work/analytics?period=7d\"",- "parameters": "name (string, path, required): Profile name; period (string, query, optional: \"1d\",\"7d\",\"30d\", default: \"7d\")",- "payload": "N/A (GET request)"- },- {- "method": "GET",- "path": "/profiles/{name}/logs",- "handler": "handleLogsByPath",- "description": "Profile logs",- "curl": true,- "examples": {},- "tldr": "Get logs for a profile",- "cli": false,- "curlExample": "curl \"http://localhost:9867/profiles/work/logs?limit=100&level=info\"",- "parameters": "name (string, path, required): Profile name; limit (int, query, optional, default: 100); level (string, query, optional: \"debug\",\"info\",\"warn\",\"error\")",- "payload": "N/A (GET request)"- },{"method": "GET","path": "/screencast",@@ -373,32 +307,6 @@"examples": {},"html": true},- {- "method": "PATCH",- "path": "/profiles/meta",- "handler": "handleUpdateMeta",- "description": "Update profile metadata",- "curl": true,- "examples": {},- "tldr": "Update profile metadata globally",- "cli": false,- "curlExample": "curl -X PATCH http://localhost:9867/profiles/meta -H \"Content-Type: application/json\" -d '{\"version\":\"2.0\"}'",- "parameters": "None",- "payload": "{\"version\":\"2.0\",\"tags\":[\"important\"]}"- },- {- "method": "PATCH",- "path": "/profiles/{name}",- "handler": "handleUpdateByPath",- "description": "Manage profile",- "curl": true,- "examples": {},- "tldr": "Update a profile",- "cli": false,- "curlExample": "curl -X PATCH http://localhost:9867/profiles/work -H \"Content-Type: application/json\" -d '{\"description\":\"Updated\"}'",- "parameters": "name (string, path, required): Profile name",- "payload": "{\"description\":\"new description\",\"tags\":[\"tag1\"]}"- },{"method": "POST","path": "/action",@@ -616,71 +524,6 @@"curl": true,"examples": {}},- {- "method": "POST",- "path": "/profiles/create",- "handler": "handleCreate",- "description": "Create profile",- "curl": true,- "examples": {},- "tldr": "Create a new browser profile",- "cli": false,- "curlExample": "curl -X POST http://localhost:9867/profiles/create -H \"Content-Type: application/json\" -d '{\"name\":\"work\"}'",- "parameters": "None",- "payload": "{\"name\":\"work\",\"description\":\"Work account\"}"- },- {- "method": "POST",- "path": "/profiles/import",- "handler": "handleImport",- "description": "Import profile",- "curl": true,- "examples": {},- "tldr": "Import a profile from backup/archive",- "cli": false,- "curlExample": "curl -X POST http://localhost:9867/profiles/import -F \"[email protected]\" -F \"name=imported-profile\"",- "parameters": "None",- "payload": "FormData with file and name"- },- {- "method": "POST",- "path": "/profiles/{id}/start",- "handler": "handleStartByID",- "description": "Start profile instance",- "curl": true,- "examples": {},- "tldr": "Start/launch a profile (create instance)",- "cli": false,- "curlExample": "curl -X POST http://localhost:9867/profiles/abc123/start -H \"Content-Type: application/json\" -d '{\"headless\":true}'",- "parameters": "id (string, path, required): Profile ID",- "payload": "{\"headless\":true,\"port\":9868}"- },- {- "method": "POST",- "path": "/profiles/{id}/stop",- "handler": "handleStopByID",- "description": "Stop profile instance",- "curl": true,- "examples": {},- "tldr": "Stop/shutdown a profile instance",- "cli": false,- "curlExample": "curl -X POST http://localhost:9867/profiles/abc123/stop",- "parameters": "id (string, path, required): Profile ID",- "payload": "N/A or {\"force\":false}"- },- {- "method": "POST",- "path": "/profiles/{name}/reset",- "handler": "handleResetByPath",- "description": "Reset profile",- "curl": true,- "examples": {},- "tldr": "Reset a profile (clear cookies, cache, history)",- "cli": false,- "curlExample": "curl -X POST http://localhost:9867/profiles/work/reset",- "parameters": "name (string, path, required): Profile name",- "payload": "N/A or {\"keepCookies\":false,\"keepHistory\":false}"- },{"method": "POST","path": "/start/{id}",@@ -729,6 +572,144 @@"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\",\"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": "Creates profile directory at ~/.pinchtab/profiles/{name}/Default",+ "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/278be873adeb",+ "curlExampleOutput": "{\"id\":\"278be873adeb\",\"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/my-profile",+ "curlExampleOutput": "{\"status\":\"deleted\",\"id\":\"my-profile\",\"name\":\"my-profile\"}",+ "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/my-profile -H \"Content-Type: application/json\" -d '{\"description\":\"Updated description\",\"useWhen\":\"New use case\"}'",+ "curlExampleOutput": "{\"status\":\"updated\",\"id\":\"my-profile\",\"name\":\"my-profile\"}",+ "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/my-profile/reset",+ "curlExampleOutput": "{\"status\":\"reset\",\"id\":\"my-profile\",\"name\":\"my-profile\"}",+ "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/my-profile/logs?limit=50'",+ "curlExampleOutput": "[{\"timestamp\":\"2026-03-01T05:12:45Z\",\"action\":\"navigate\",\"url\":\"https://example.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/my-profile/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": {}}]}diff --git a/internal/profiles/handlers.go b/internal/profiles/handlers.goindex aa0f98af..8fea4efc 100644--- a/internal/profiles/handlers.go+++ b/internal/profiles/handlers.go@@ -4,21 +4,28 @@ import ("encoding/json""fmt""net/http"+ "os"+ "path/filepath""strconv""github.com/pinchtab/pinchtab/internal/web")func (pm *ProfileManager) RegisterHandlers(mux *http.ServeMux) {+ // Standard CRUD endpointsmux.HandleFunc("GET /profiles", pm.handleList)- mux.HandleFunc("POST /profiles/create", pm.handleCreate)+ mux.HandleFunc("POST /profiles", pm.handleCreate) // RESTful: POST /profiles instead of /profiles/create+ mux.HandleFunc("POST /profiles/create", pm.handleCreate) // Backward compat+ mux.HandleFunc("GET /profiles/{id}", pm.handleGetByID) // Get single profile by ID or name++ // Advanced endpoints (specific paths, no conflict with {id})mux.HandleFunc("POST /profiles/import", pm.handleImport)mux.HandleFunc("PATCH /profiles/meta", pm.handleUpdateMeta)- mux.HandleFunc("DELETE /profiles/{name}", pm.handleDeleteByPath)- mux.HandleFunc("PATCH /profiles/{name}", pm.handleUpdateByPath)- mux.HandleFunc("POST /profiles/{name}/reset", pm.handleResetByPath)- mux.HandleFunc("GET /profiles/{name}/logs", pm.handleLogsByPath)- mux.HandleFunc("GET /profiles/{name}/analytics", pm.handleAnalyticsByPath)+ mux.HandleFunc("POST /profiles/{id}/reset", pm.handleResetByIDOrName) // Reset profile+ mux.HandleFunc("GET /profiles/{id}/logs", pm.handleLogsByIDOrName) // Get logs+ mux.HandleFunc("GET /profiles/{id}/analytics", pm.handleAnalyticsByIDOrName) // Get analytics+ mux.HandleFunc("DELETE /profiles/{id}", pm.handleDeleteByID) // Delete profile+ mux.HandleFunc("PATCH /profiles/{id}", pm.handleUpdateByIDOrName) // Update profile metadata}func (pm *ProfileManager) handleList(w http.ResponseWriter, r *http.Request) {@@ -144,7 +151,180 @@ func (pm *ProfileManager) handleUpdateMeta(w http.ResponseWriter, r *http.Requesweb.JSON(w, 200, map[string]string{"status": "updated", "name": req.Name})}-// Path-param compat handlers for dashboard JS+// New RESTful handlers++func (pm *ProfileManager) handleGetByID(w http.ResponseWriter, r *http.Request) {+ id := r.PathValue("id")++ // Try to find profile by ID first+ pm.mu.RLock()+ entries, err := os.ReadDir(pm.baseDir)+ pm.mu.RUnlock()++ if err != nil {+ web.Error(w, 500, err)+ return+ }++ var foundProfile map[string]any++ for _, entry := range entries {+ if !entry.IsDir() {+ continue+ }++ meta := readProfileMeta(filepath.Join(pm.baseDir, entry.Name()))+ if meta.ID == "" {+ meta.ID = profileID(entry.Name())+ }++ // If ID matches, or if id looks like a name (for backward compat)+ if meta.ID == id || entry.Name() == id {+ info, err := pm.profileInfo(entry.Name())+ if err != nil {+ continue+ }++ foundProfile = map[string]any{+ "id": info.ID,+ "name": info.Name,+ "created": info.CreatedAt,+ "diskUsage": info.SizeMB * 1024 * 1024,+ "source": info.Source,+ "chromeProfileName": info.ChromeProfileName,+ "accountEmail": info.AccountEmail,+ "accountName": info.AccountName,+ "hasAccount": info.HasAccount,+ "useWhen": info.UseWhen,+ "description": info.Description,+ }+ break+ }+ }++ if foundProfile == nil {+ web.Error(w, 404, fmt.Errorf("profile %q not found", id))+ return+ }++ web.JSON(w, 200, foundProfile)+}++func (pm *ProfileManager) handleDeleteByID(w http.ResponseWriter, r *http.Request) {+ id := r.PathValue("id")++ // Find profile name by ID+ name, err := pm.FindByID(id)+ if err != nil {+ // Try as name directly (backward compat)+ name = id+ if !pm.Exists(name) {+ web.Error(w, 404, fmt.Errorf("profile %q not found", id))+ return+ }+ }++ if err := pm.Delete(name); err != nil {+ web.Error(w, 404, err)+ return+ }++ web.JSON(w, 200, map[string]any{"status": "deleted", "id": id, "name": name})+}++// Helper to find profile name by ID or use as name directly+func (pm *ProfileManager) resolveIDOrName(idOrName string) (string, error) {+ // Try as ID first+ name, err := pm.FindByID(idOrName)+ if err == nil {+ return name, nil+ }+ // Try as name directly+ if pm.Exists(idOrName) {+ return idOrName, nil+ }+ return "", fmt.Errorf("profile %q not found (not a valid ID or name)", idOrName)+}++// Consolidated handlers that work with both ID and name++func (pm *ProfileManager) handleUpdateByIDOrName(w http.ResponseWriter, r *http.Request) {+ idOrName := r.PathValue("id")+ name, err := pm.resolveIDOrName(idOrName)+ if err != nil {+ web.Error(w, 404, err)+ return+ }++ var req struct {+ Name string `json:"name"`+ UseWhen string `json:"useWhen"`+ Description string `json:"description"`+ }+ if err := json.NewDecoder(r.Body).Decode(&req); err != nil {+ web.Error(w, 400, fmt.Errorf("invalid JSON"))+ return+ }++ updates := make(map[string]string)+ if req.Description != "" {+ updates["description"] = req.Description+ }+ if req.UseWhen != "" {+ updates["useWhen"] = req.UseWhen+ }+ if len(updates) > 0 {+ if err := pm.UpdateMeta(name, updates); err != nil {+ web.Error(w, 404, err)+ return+ }+ }++ web.JSON(w, 200, map[string]any{"status": "updated", "id": idOrName, "name": name})+}++func (pm *ProfileManager) handleResetByIDOrName(w http.ResponseWriter, r *http.Request) {+ idOrName := r.PathValue("id")+ name, err := pm.resolveIDOrName(idOrName)+ if err != nil {+ web.Error(w, 404, err)+ return+ }++ if err := pm.Reset(name); err != nil {+ web.Error(w, 404, err)+ return+ }+ web.JSON(w, 200, map[string]any{"status": "reset", "id": idOrName, "name": name})+}++func (pm *ProfileManager) handleLogsByIDOrName(w http.ResponseWriter, r *http.Request) {+ idOrName := r.PathValue("id")+ name, err := pm.resolveIDOrName(idOrName)+ if err != nil {+ web.Error(w, 404, err)+ return+ }++ limit, _ := strconv.Atoi(r.URL.Query().Get("limit"))+ logs := pm.Logs(name, limit)+ web.JSON(w, 200, logs)+}++func (pm *ProfileManager) handleAnalyticsByIDOrName(w http.ResponseWriter, r *http.Request) {+ idOrName := r.PathValue("id")+ name, err := pm.resolveIDOrName(idOrName)+ if err != nil {+ web.Error(w, 404, err)+ return+ }++ report := pm.Analytics(name)+ web.JSON(w, 200, report)+}++// OLD: Path-param compat handlers for dashboard JS (deprecated - kept for legacy support if needed)+// These are now handled above with {id} pattern that accepts both IDs and namesfunc (pm *ProfileManager) handleDeleteByPath(w http.ResponseWriter, r *http.Request) {name := r.PathValue("name")