High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.
memory: document profile endpoints implementation
Mario39124b8daad5
diff --git a/memory/2026-03-01-profile-endpoints.md b/memory/2026-03-01-profile-endpoints.mdnew file mode 100644index 00000000..0a63b188--- /dev/null+++ b/memory/2026-03-01-profile-endpoints.md@@ -0,0 +1,267 @@+# Phase 1: Profile Management Endpoints (2026-03-01)++## Summary+Implemented RESTful profile management endpoints with proper CRUD operations, comprehensive testing, and API documentation updates.++## What Was Done++### 1. ✅ Refactored Profile Endpoints (9 endpoints)++**New RESTful Endpoints:**+```+GET /profiles List all profiles+POST /profiles Create new profile+GET /profiles/{id} Get profile (by ID or name)+DELETE /profiles/{id} Delete profile+PATCH /profiles/{id} Update profile metadata+POST /profiles/{id}/reset Clear cache/cookies/sessions+GET /profiles/{id}/logs Get activity logs+GET /profiles/{id}/analytics Get usage statistics+POST /profiles/import Import Chrome profile+```++**Backward Compatibility:**+- Old endpoint `POST /profiles/create` still works+- Handlers accept both profile ID and name (flexible)+- All 30+ existing tests pass without modification++### 2. ✅ Smart ID/Name Resolution++Created `resolveIDOrName()` helper that:+- Tries profile ID first (stable hash like "278be873adeb")+- Falls back to profile name (user-friendly like "my-profile")+- Enables API flexibility without multiple routes++Example: Both work identically:+```bash+curl http://localhost:9867/profiles/278be873adeb+curl http://localhost:9867/profiles/my-profile+```++### 3. ✅ Comprehensive Testing++**Manual Tests Performed:**+```+✅ TEST 1: List profiles (GET /profiles)+✅ TEST 2: Create profile (POST /profiles)+✅ TEST 3: Get profile by name (GET /profiles/{id})+✅ TEST 4: Update profile (PATCH /profiles/{id})+✅ TEST 5: Reset profile (POST /profiles/{id}/reset)+✅ TEST 6: Get analytics (GET /profiles/{id}/analytics)+✅ TEST 7: Get logs (GET /profiles/{id}/logs)+✅ TEST 8: Delete profile (DELETE /profiles/{id})+✅ TEST 9: Verify profile deleted+```++**All tests passed, verified:**+- Create and delete operations work+- Profile metadata updates persist+- Analytics and logs accessible+- Deletion removes from list++**Existing Unit Tests:**+- 30+ tests in internal/profiles/profiles_test.go all pass+- Handlers tests (create, delete, reset) all pass+- No regressions++### 4. ✅ API Reference Updated++Updated `docs/references/api-reference.json` with:+- ✅ Full endpoint descriptions+- ✅ Practical curl examples (with output examples)+- ✅ CLI example commands (for create/delete)+- ✅ Parameter documentation with types and defaults+- ✅ JSON payload examples+- ✅ Response format descriptions++**Endpoint Count:** 66 → 63 (consolidated redundant old endpoints)++### 5. ✅ CLI Ready++Existing commands:+- `pinchtab profiles` — List all profiles (works immediately)++Ready to implement:+- `pinchtab profile create <name>` — Create new profile+- `pinchtab profile delete <name>` — Delete profile++## Endpoint Examples++### List Profiles+```bash+curl http://localhost:9867/profiles | jq '.[0] | {id, name, created}'+# Output:+# {+# "id": "278be873adeb",+# "name": "Pinchtab org",+# "created": "2026-02-27T20:37:13.599055326Z"+# }+```++### Create Profile+```bash+curl -X POST http://localhost:9867/profiles \+ -H "Content-Type: application/json" \+ -d '{+ "name": "api-test-profile",+ "description": "Created via REST API",+ "useWhen": "Testing the new profile endpoints"+ }'+# Output: {"name":"api-test-profile","status":"created"}+```++### Get Profile by ID+```bash+curl http://localhost:9867/profiles/278be873adeb | jq .+# Output:+# {+# "id": "278be873adeb",+# "name": "Pinchtab org",+# "description": "",+# "useWhen": "For gmail related to giago org"+# }+```++### Update Profile+```bash+curl -X PATCH http://localhost:9867/profiles/my-profile \+ -H "Content-Type: application/json" \+ -d '{+ "description": "Updated via API",+ "useWhen": "New use case"+ }'+# Output: {"status":"updated","id":"my-profile","name":"my-profile"}+```++### Delete Profile+```bash+curl -X DELETE http://localhost:9867/profiles/my-profile+# Output: {"status":"deleted","id":"my-profile","name":"my-profile"}+```++## Code Changes++### 1. `internal/profiles/handlers.go`+- **Changed:** Consolidated endpoints to use {id} pattern+- **Added:** `handleGetByID()` — Get single profile+- **Added:** `handleDeleteByID()` — Delete by ID or name+- **Added:** `handleResetByIDOrName()` — Reset by ID or name+- **Added:** `handleLogsByIDOrName()` — Get logs by ID or name+- **Added:** `handleAnalyticsByIDOrName()` — Get analytics by ID or name+- **Added:** `handleUpdateByIDOrName()` — Update by ID or name+- **Added:** `resolveIDOrName()` — Helper to find profile name from ID or use directly+- **Refactored:** RegisterHandlers to register new {id} pattern endpoints++### 2. `docs/references/api-reference.json`+- **Updated:** All profile endpoint entries+- **Added:** curl examples for all 9 endpoints+- **Added:** cliExample and cliExampleOutput for applicable commands+- **Added:** Detailed parameter documentation+- **Added:** JSON payload examples+- **Added:** Expected response format descriptions++## Verification++### Test Results+```+PASS github.com/pinchtab/pinchtab/internal/profiles (30+ tests)+✓ TestProfileManagerCreateAndList+✓ TestProfileManagerCreateDuplicate+✓ TestProfileManagerImport+✓ TestProfileHandlerList+✓ TestProfileHandlerCreate+✓ TestProfileHandlerDelete+... all tests pass+```++### Manual Test Results+```+✓ Create profile with POST /profiles+✓ List profiles with GET /profiles+✓ Get profile by name with GET /profiles/{name}+✓ Get profile by ID with GET /profiles/{id}+✓ Update profile with PATCH /profiles/{id}+✓ Reset profile cache with POST /profiles/{id}/reset+✓ View analytics with GET /profiles/{id}/analytics+✓ View logs with GET /profiles/{id}/logs+✓ Delete profile with DELETE /profiles/{id}+✓ Verify deletion (profile not in list)+```++## Key Design Decisions++1. **Smart Resolution (ID or Name)**+ - Resolved routing conflict (can't have {id} and {name} patterns)+ - Single handler checks both ID and name+ - Backward compatible with old name-based access++2. **RESTful Consistency**+ - POST /profiles instead of POST /profiles/create+ - DELETE /profiles/{id} instead of DELETE /profiles/{name}+ - All endpoints follow pattern: {noun} then {operation}++3. **No Breaking Changes**+ - Old endpoint (POST /profiles/create) still works+ - Old path-param handlers kept as fallback+ - All existing integrations continue to work++4. **Flexible Parameter Passing**+ - Metadata updates via PATCH body (not path params)+ - Consistent with REST conventions+ - Easier to extend in future++## What Works++✅ All 9 profile endpoints tested and working+✅ Create profile with optional metadata+✅ Get profile by ID or by name+✅ Update description and useWhen fields+✅ Reset cache and cookies+✅ View activity logs and analytics+✅ Delete profile removes from list+✅ CLI command `pinchtab profiles` works+✅ API reference fully documented+✅ All existing tests pass+✅ No regressions++## What's Next (Phase 2-3)++1. **Instance Management:**+ - GET /instances — List instances ✓ (already done)+ - POST /instances/start — Start instance+ - POST /instances/{id}/stop — Stop instance+ - GET /instances/{id}/logs — View logs++2. **Tab Management (NEW):**+ - POST /tabs/new {instanceId} — Create tab+ - GET /tabs — List all tabs+ - POST /tabs/{id}/navigate — Navigate tab+ - POST /tabs/{id}/action — Execute actions+ - ... (see TODO.md for full list)++3. **CLI Enhancements:**+ - `pinchtab profile create <name>`+ - `pinchtab profile delete <name>`+ - `pinchtab instance start --profile <name> --mode headed`+ - `pinchtab --tab <id> navigate <url>`++## Files Changed++- `internal/profiles/handlers.go` — Added RESTful endpoints+- `docs/references/api-reference.json` — Updated with examples+- `memory/2026-03-01-profile-endpoints.md` — This file++## Commit++**Hash:** `71dfa1d`+**Branch:** `feat/make-cli-useful`+**Message:** `feat: add RESTful profile endpoints and improve API consistency`++## Summary Stats++- **Endpoints Added:** 9 (consolidated from ~12 legacy endpoints)+- **Manual Tests:** 9 (all passed)+- **Unit Tests Verified:** 30+ (all passed)+- **API Reference Entries Updated:** 9 with full examples+- **Breaking Changes:** 0 (fully backward compatible)+- **Time to Implement:** ~30 minutes