reverse-api-engineer 0.2.4__tar.gz → 0.2.6__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (37) hide show
  1. reverse_api_engineer-0.2.6/.claude/settings.local.json +49 -0
  2. {reverse_api_engineer-0.2.4 → reverse_api_engineer-0.2.6}/.gitignore +3 -4
  3. {reverse_api_engineer-0.2.4 → reverse_api_engineer-0.2.6}/CHANGELOG.md +23 -0
  4. reverse_api_engineer-0.2.6/PKG-INFO +312 -0
  5. reverse_api_engineer-0.2.6/README.md +277 -0
  6. {reverse_api_engineer-0.2.4 → reverse_api_engineer-0.2.6}/pyproject.toml +1 -1
  7. reverse_api_engineer-0.2.6/scripts/clean_build.sh +31 -0
  8. {reverse_api_engineer-0.2.4 → reverse_api_engineer-0.2.6}/src/reverse_api/__init__.py +1 -1
  9. {reverse_api_engineer-0.2.4 → reverse_api_engineer-0.2.6}/src/reverse_api/opencode_engineer.py +5 -2
  10. reverse_api_engineer-0.2.4/.claude/settings.local.json +0 -24
  11. reverse_api_engineer-0.2.4/PKG-INFO +0 -339
  12. reverse_api_engineer-0.2.4/README.md +0 -304
  13. reverse_api_engineer-0.2.4/scripts/fetch_all_jobs/README.md +0 -463
  14. reverse_api_engineer-0.2.4/scripts/fetch_all_jobs/api_client.py +0 -856
  15. reverse_api_engineer-0.2.4/scripts/post_x/README.md +0 -237
  16. reverse_api_engineer-0.2.4/scripts/post_x/api_client.py +0 -376
  17. reverse_api_engineer-0.2.4/scripts/post_x/example_usage.py +0 -195
  18. reverse_api_engineer-0.2.4/scripts/web_scraping_task/README.md +0 -369
  19. reverse_api_engineer-0.2.4/scripts/web_scraping_task/api_client.py +0 -435
  20. reverse_api_engineer-0.2.4/scripts/web_scraping_task/example_usage.py +0 -192
  21. {reverse_api_engineer-0.2.4 → reverse_api_engineer-0.2.6}/.python-version +0 -0
  22. {reverse_api_engineer-0.2.4 → reverse_api_engineer-0.2.6}/CONTRIBUTING.md +0 -0
  23. {reverse_api_engineer-0.2.4 → reverse_api_engineer-0.2.6}/LICENSE +0 -0
  24. {reverse_api_engineer-0.2.4 → reverse_api_engineer-0.2.6}/assets/reverse-api-banner.svg +0 -0
  25. {reverse_api_engineer-0.2.4 → reverse_api_engineer-0.2.6}/assets/reverse-api-engineer.gif +0 -0
  26. {reverse_api_engineer-0.2.4 → reverse_api_engineer-0.2.6}/assets/reverse-api-logo.svg +0 -0
  27. {reverse_api_engineer-0.2.4 → reverse_api_engineer-0.2.6}/src/reverse_api/base_engineer.py +0 -0
  28. {reverse_api_engineer-0.2.4 → reverse_api_engineer-0.2.6}/src/reverse_api/browser.py +0 -0
  29. {reverse_api_engineer-0.2.4 → reverse_api_engineer-0.2.6}/src/reverse_api/cli.py +0 -0
  30. {reverse_api_engineer-0.2.4 → reverse_api_engineer-0.2.6}/src/reverse_api/config.py +0 -0
  31. {reverse_api_engineer-0.2.4 → reverse_api_engineer-0.2.6}/src/reverse_api/engineer.py +0 -0
  32. {reverse_api_engineer-0.2.4 → reverse_api_engineer-0.2.6}/src/reverse_api/messages.py +0 -0
  33. {reverse_api_engineer-0.2.4 → reverse_api_engineer-0.2.6}/src/reverse_api/opencode_ui.py +0 -0
  34. {reverse_api_engineer-0.2.4 → reverse_api_engineer-0.2.6}/src/reverse_api/session.py +0 -0
  35. {reverse_api_engineer-0.2.4 → reverse_api_engineer-0.2.6}/src/reverse_api/tui.py +0 -0
  36. {reverse_api_engineer-0.2.4 → reverse_api_engineer-0.2.6}/src/reverse_api/utils.py +0 -0
  37. {reverse_api_engineer-0.2.4 → reverse_api_engineer-0.2.6}/uv.lock +0 -0
@@ -0,0 +1,49 @@
1
+ {
2
+ "permissions": {
3
+ "allow": [
4
+ "WebFetch(domain:docs.browser-use.com)",
5
+ "Bash(git -C /Users/kalilbouzigues/Projects/browgents/reverse-api log --oneline)",
6
+ "Bash(python -c:*)",
7
+ "Bash(uv sync:*)",
8
+ "Bash(uv pip index versions:*)",
9
+ "Bash(pip index:*)",
10
+ "Bash(source:*)",
11
+ "WebSearch",
12
+ "WebFetch(domain:github.com)",
13
+ "WebFetch(domain:pypi.org)",
14
+ "WebFetch(domain:docs.stagehand.dev)",
15
+ "Bash(python -m py_compile:*)",
16
+ "Bash(find:*)",
17
+ "Bash(cat:*)",
18
+ "Bash(chmod:*)",
19
+ "Bash(python3:*)",
20
+ "Bash(grep:*)",
21
+ "Bash(./scripts/clean_build.sh:*)",
22
+ "Bash(git add:*)",
23
+ "Bash(uv publish)",
24
+ "Bash(export:*)",
25
+ "Bash(uv tool install:*)",
26
+ "Bash(uv cache clean:*)",
27
+ "Bash(reverse-api-engineer:*)",
28
+ "Bash(git tag:*)",
29
+ "Bash(git push:*)",
30
+ "Bash(git show:*)",
31
+ "Bash(~/.local/bin/reverse-api-engineer:*)",
32
+ "Bash(deactivate)",
33
+ "Bash(test_env/bin/pip install:*)",
34
+ "Bash(test_env/bin/reverse-api-engineer:*)",
35
+ "Bash(uv tool uninstall:*)",
36
+ "Bash(echo:*)",
37
+ "Bash(/Users/kalilbouzigues/.local/share/uv/tools/reverse-api-engineer/bin/reverse-api-engineer:*)",
38
+ "Bash(/Users/kalilbouzigues/.local/share/uv/tools/reverse-api-engineer/bin/python:*)",
39
+ "Bash(uv tool:*)",
40
+ "Bash(.venv/bin/python:*)",
41
+ "Bash(.venv/bin/reverse-api-engineer:*)",
42
+ "Bash(/Users/kalilbouzigues/.local/bin/reverse-api-engineer:*)",
43
+ "Bash(/opt/homebrew/bin/reverse-api-engineer:*)",
44
+ "Bash(/opt/homebrew/opt/python@3.14/bin/python3.14 -m pip:*)",
45
+ "Bash(pipx list:*)",
46
+ "Bash(git commit:*)"
47
+ ]
48
+ }
49
+ }
@@ -77,11 +77,10 @@ cython_debug/
77
77
 
78
78
  # Project specific
79
79
  har/
80
- scripts/
80
+ scripts/*
81
+ !scripts/clean_build.sh
81
82
  scripts_built/
82
- !scripts/*/api_client.py
83
- !scripts/*/example_usage.py
84
- !scripts/*/README.md
83
+ src/reverse_api/scripts/
85
84
  .reverse-api/
86
85
  *.har
87
86
 
@@ -5,6 +5,29 @@ All notable changes to this project will be documented in this file.
5
5
  The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
6
6
  and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
7
 
8
+ ## [0.2.6] - 2025-12-27
9
+
10
+ ### Fixed
11
+ - **Version flag**: Updated `__version__` to 0.2.6 to ensure `--version` displays correctly
12
+ - **OpenCodeEngineer initialization**: Refactored to properly pop specific kwargs (`opencode_provider` and `opencode_model`) before passing to parent class
13
+ - Ensures only relevant arguments are sent to BaseEngineer
14
+ - Improves initialization logic clarity and prevents unintended argument passing
15
+
16
+ ### Changed
17
+ - **README improvements**: Added table of contents and removed repetitive sections for better readability
18
+
19
+ ## [0.2.5] - 2025-12-27
20
+
21
+ ### Fixed
22
+ - Initial release attempt (superseded by 0.2.6 due to missing version flag update)
23
+
24
+ ## [0.2.4] - 2025-12-27
25
+
26
+ ### Fixed
27
+ - **Version string**: Fixed `--version` flag to correctly display 0.2.4 instead of outdated 0.2.0
28
+ - Previous release (0.2.3) was built with stale bytecode cache
29
+ - Added clean build script (`scripts/clean_build.sh`) to prevent future stale builds
30
+
8
31
  ## [0.2.3] - 2025-12-27
9
32
 
10
33
  ### Changed
@@ -0,0 +1,312 @@
1
+ Metadata-Version: 2.4
2
+ Name: reverse-api-engineer
3
+ Version: 0.2.6
4
+ Summary: A tool to capture browser traffic for API reverse engineering
5
+ Project-URL: Homepage, https://github.com/kalil0321/reverse-api-engineer
6
+ Project-URL: Repository, https://github.com/kalil0321/reverse-api-engineer
7
+ Project-URL: Issues, https://github.com/kalil0321/reverse-api-engineer/issues
8
+ Author-email: Kalil <kalil0321@users.noreply.github.com>
9
+ License: MIT
10
+ License-File: LICENSE
11
+ Keywords: api,browser,claude,har,playwright,reverse-engineering
12
+ Classifier: Development Status :: 3 - Alpha
13
+ Classifier: Intended Audience :: Developers
14
+ Classifier: License :: OSI Approved :: MIT License
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Programming Language :: Python :: 3.11
17
+ Classifier: Programming Language :: Python :: 3.12
18
+ Classifier: Programming Language :: Python :: 3.13
19
+ Classifier: Topic :: Internet :: WWW/HTTP
20
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
21
+ Requires-Python: >=3.11
22
+ Requires-Dist: aiohttp>=3.12.15
23
+ Requires-Dist: anthropic>=0.40.0
24
+ Requires-Dist: brotli>=1.2.0
25
+ Requires-Dist: claude-agent-sdk>=0.1.0
26
+ Requires-Dist: click>=8.1.0
27
+ Requires-Dist: playwright-stealth>=1.0.0
28
+ Requires-Dist: playwright>=1.40.0
29
+ Requires-Dist: questionary>=2.0.0
30
+ Requires-Dist: requests>=2.32.5
31
+ Requires-Dist: rich>=13.0.0
32
+ Provides-Extra: agent
33
+ Requires-Dist: stagehand; extra == 'agent'
34
+ Description-Content-Type: text/markdown
35
+
36
+ <div align="center">
37
+ <img src="assets/reverse-api-banner.svg" alt="Reverse API Engineer Banner">
38
+ </div>
39
+
40
+ # Reverse API Engineer
41
+
42
+ [![PyPI version](https://badge.fury.io/py//reverse-api-engineer.svg)](https://badge.fury.io/py/reverse-api-engineer)
43
+ [![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
44
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
45
+
46
+ CLI tool that captures browser traffic and automatically generates production-ready Python API clients. No more manual reverse engineering—just browse, capture, and get clean API code.
47
+
48
+ ![Reverse API Engineer Demo](assets/reverse-api-engineer.gif)
49
+
50
+ ## Table of Contents
51
+
52
+ - [Features](#-features)
53
+ - [Installation](#-installation)
54
+ - [Quick Start](#-quick-start)
55
+ - [Usage Modes](#-usage-modes)
56
+ - [Manual Mode](#manual-mode)
57
+ - [Engineer Mode](#engineer-mode)
58
+ - [Agent Mode](#agent-mode)
59
+ - [Configuration](#-configuration)
60
+ - [Model Selection](#model-selection)
61
+ - [Agent Configuration](#agent-configuration)
62
+ - [SDK Selection](#sdk-selection)
63
+ - [CLI Commands](#-cli-commands)
64
+ - [Examples](#-examples)
65
+ - [Development](#-development)
66
+ - [Contributing](#-contributing)
67
+
68
+ ## ✨ Features
69
+
70
+ - 🌐 **Browser Automation**: Built on Playwright with stealth mode for realistic browsing
71
+ - 🤖 **Autonomous Agent Mode**: Fully automated browser interaction using AI agents (browser-use, stagehand)
72
+ - 📊 **HAR Recording**: Captures all network traffic in HTTP Archive format
73
+ - 🧠 **AI-Powered Generation**: Uses Claude 4.5 to analyze traffic and generate clean Python code
74
+ - 🔌 **Multi-SDK Support**: Native integration with Claude and OpenCode SDKs
75
+ - 💻 **Interactive CLI**: Minimalist terminal interface with mode cycling (Shift+Tab)
76
+ - 📦 **Production Ready**: Generated scripts include error handling, type hints, and documentation
77
+ - 💾 **Session History**: All runs saved locally with full message logs
78
+ - 💰 **Cost Tracking**: Detailed token usage and cost estimation with cache support
79
+
80
+ ### Limitations
81
+
82
+ - This tool executes code locally using Claude Code—please monitor output
83
+ - Some websites employ advanced bot-detection that may limit capture or require manual interaction
84
+
85
+ ## 🚀 Installation
86
+
87
+ ### Using uv (recommended)
88
+ ```bash
89
+ # Basic installation
90
+ uv tool install reverse-api-engineer
91
+
92
+ # With agent mode support (includes browser-use with HAR recording)
93
+ uv tool install 'reverse-api-engineer[agent]' --with 'browser-use @ git+https://github.com/browser-use/browser-use.git@49a345fb19e9f12befc5cc1658e0033873892455'
94
+ ```
95
+
96
+ ### Using pip
97
+ ```bash
98
+ # Basic installation
99
+ pip install reverse-api-engineer
100
+
101
+ # With agent mode support
102
+ pip install 'reverse-api-engineer[agent]'
103
+ pip install git+https://github.com/browser-use/browser-use.git@49a345fb19e9f12befc5cc1658e0033873892455
104
+ ```
105
+
106
+ ### Post-installation
107
+ Install Playwright browsers:
108
+ ```bash
109
+ playwright install chromium
110
+ ```
111
+
112
+ ## 🚀 Quick Start
113
+
114
+ Launch the interactive CLI:
115
+ ```bash
116
+ reverse-api-engineer
117
+ ```
118
+
119
+ The CLI has three modes (cycle with **Shift+Tab**):
120
+ - **manual**: Browser capture + AI generation
121
+ - **engineer**: Re-process existing captures
122
+ - **agent**: Autonomous AI browser agent
123
+
124
+ Example workflow:
125
+ ```bash
126
+ $ reverse-api-engineer
127
+ > fetch all apple jobs from their careers page
128
+
129
+ # Browser opens, navigate and interact
130
+ # Close browser when done
131
+ # AI generates production-ready API client
132
+
133
+ # Scripts saved to: ./scripts/apple_jobs_api/
134
+ ```
135
+
136
+ ## 📖 Usage Modes
137
+
138
+ ### Manual Mode
139
+
140
+ Full pipeline with manual browser interaction:
141
+
142
+ 1. Start the CLI: `reverse-api-engineer`
143
+ 2. Enter task description (e.g., "Fetch Apple job listings")
144
+ 3. Optionally provide starting URL
145
+ 4. Browse and interact with the website
146
+ 5. Close browser when done
147
+ 6. AI automatically generates the API client
148
+
149
+ **Output locations:**
150
+ - `~/.reverse-api/runs/scripts/{run_id}/` (permanent storage)
151
+ - `./scripts/{descriptive_name}/` (local copy with readable name)
152
+
153
+ ### Engineer Mode
154
+
155
+ Re-run AI generation on a previous capture:
156
+ ```bash
157
+ # Switch to engineer mode (Shift+Tab) and enter run_id
158
+ # Or use command line:
159
+ reverse-api-engineer engineer <run_id>
160
+ ```
161
+
162
+ ### Agent Mode
163
+
164
+ Fully automated browser interaction using AI agents:
165
+
166
+ 1. Install with agent support (see [Installation](#-installation))
167
+ 2. Start CLI and switch to agent mode (Shift+Tab)
168
+ 3. Enter task description (e.g., "Click on the first job listing")
169
+ 4. Optionally provide starting URL
170
+ 5. Agent automatically navigates and interacts
171
+ 6. HAR captured automatically
172
+ 7. Optionally generate API client
173
+
174
+ **Note:** Requires browser-use from the specific git commit shown in installation instructions (includes HAR recording support).
175
+
176
+ ## 🔧 Configuration
177
+
178
+ Settings stored in `~/.reverse-api/config.json`:
179
+ ```json
180
+ {
181
+ "model": "claude-sonnet-4-5",
182
+ "sdk": "claude",
183
+ "agent_provider": "browser-use",
184
+ "agent_model": "bu-llm",
185
+ "output_dir": null
186
+ }
187
+ ```
188
+
189
+ ### Model Selection
190
+
191
+ Choose from Claude 4.5 models for API generation:
192
+ - **Sonnet 4.5** (default): Balanced performance and cost
193
+ - **Opus 4.5**: Maximum capability for complex APIs
194
+ - **Haiku 4.5**: Fastest and most economical
195
+
196
+ Change in `/settings` or via CLI:
197
+ ```bash
198
+ reverse-api-engineer manual --model claude-sonnet-4-5
199
+ ```
200
+
201
+ ### Agent Configuration
202
+
203
+ Configure AI agents for autonomous browser automation.
204
+
205
+ **Agent Providers:**
206
+ - **browser-use** (default): Supports Browser-Use LLM, OpenAI, and Google models
207
+ - **stagehand**: Supports OpenAI and Anthropic Computer Use models
208
+
209
+ **Agent Models:**
210
+
211
+ **Browser-Use Provider:**
212
+ - `bu-llm` (default) - Requires `BROWSER_USE_API_KEY`
213
+ - `openai/gpt-4`, `openai/gpt-3.5-turbo` - Requires `OPENAI_API_KEY`
214
+ - `google/gemini-pro`, `google/gemini-1.5-pro` - Requires `GOOGLE_API_KEY`
215
+
216
+ **Stagehand Provider (Computer Use only):**
217
+ - `openai/computer-use-preview-2025-03-11` - Requires `OPENAI_API_KEY`
218
+ - `anthropic/claude-sonnet-4-5-20250929` - Requires `ANTHROPIC_API_KEY`
219
+ - `anthropic/claude-haiku-4-5-20251001` - Requires `ANTHROPIC_API_KEY`
220
+ - `anthropic/claude-opus-4-5-20251101` - Requires `ANTHROPIC_API_KEY`
221
+
222
+ **Setting API Keys:**
223
+ ```bash
224
+ export BROWSER_USE_API_KEY="your-api-key" # For Browser-Use
225
+ export OPENAI_API_KEY="your-api-key" # For OpenAI models
226
+ export ANTHROPIC_API_KEY="your-api-key" # For Anthropic models
227
+ export GOOGLE_API_KEY="your-api-key" # For Google models
228
+ ```
229
+
230
+ Change in `/settings` → "agent provider" and "agent model"
231
+
232
+ ### SDK Selection
233
+
234
+ - **Claude** (default): Direct integration with Anthropic's Claude API
235
+ - **OpenCode**: Uses OpenCode SDK (requires OpenCode running locally)
236
+
237
+ Change in `/settings` or edit `config.json` directly.
238
+
239
+ ## 💻 CLI Commands
240
+
241
+ Use these slash commands while in the CLI:
242
+ - `/settings` - Configure model, agent, SDK, and output directory
243
+ - `/history` - View past runs with costs
244
+ - `/messages <run_id>` - View detailed message logs
245
+ - `/help` - Show all commands
246
+ - `/exit` - Quit
247
+
248
+ ## 💡 Examples
249
+
250
+ ### Example: Reverse Engineering a Job Board API
251
+
252
+ ```bash
253
+ $ reverse-api-engineer
254
+ > fetch all apple jobs from their careers page
255
+
256
+ # Browser opens, you navigate and interact
257
+ # Close browser when done
258
+
259
+ # AI generates:
260
+ # - api_client.py (full API implementation)
261
+ # - README.md (documentation)
262
+ # - example_usage.py (usage examples)
263
+
264
+ # Scripts copied to: ./scripts/apple_jobs_api/
265
+ ```
266
+
267
+ Generated `api_client.py` includes:
268
+ - Authentication handling
269
+ - Clean function interfaces
270
+ - Type hints and docstrings
271
+ - Error handling
272
+ - Production-ready code
273
+
274
+ ## 🛠️ Development
275
+
276
+ ### Setup
277
+ ```bash
278
+ git clone https://github.com/kalil0321/reverse-api-engineer.git
279
+ cd reverse-api-engineer
280
+ uv sync
281
+ ```
282
+
283
+ ### Run locally
284
+ ```bash
285
+ uv run reverse-api-engineer
286
+ ```
287
+
288
+ ### Build
289
+ ```bash
290
+ ./scripts/clean_build.sh
291
+ ```
292
+
293
+ ## 🗺️ Roadmap
294
+
295
+ - ✅ **Claude SDK** - Integration with Claude Code
296
+ - ✅ **OpenCode SDK** - Integration with OpenCode
297
+ - 🔄 **Codex SDK** - Codex SDK support
298
+
299
+ ## 🔐 Requirements
300
+
301
+ - Python 3.11+
302
+ - Claude Code / OpenCode (for reverse engineering)
303
+ - Playwright browsers installed
304
+ - API key for agent mode (see [Agent Configuration](#agent-configuration))
305
+
306
+ ## 🤝 Contributing
307
+
308
+ Contributions are welcome! Please feel free to submit a Pull Request.
309
+
310
+ ## 📄 License
311
+
312
+ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
@@ -0,0 +1,277 @@
1
+ <div align="center">
2
+ <img src="assets/reverse-api-banner.svg" alt="Reverse API Engineer Banner">
3
+ </div>
4
+
5
+ # Reverse API Engineer
6
+
7
+ [![PyPI version](https://badge.fury.io/py//reverse-api-engineer.svg)](https://badge.fury.io/py/reverse-api-engineer)
8
+ [![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
9
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
10
+
11
+ CLI tool that captures browser traffic and automatically generates production-ready Python API clients. No more manual reverse engineering—just browse, capture, and get clean API code.
12
+
13
+ ![Reverse API Engineer Demo](assets/reverse-api-engineer.gif)
14
+
15
+ ## Table of Contents
16
+
17
+ - [Features](#-features)
18
+ - [Installation](#-installation)
19
+ - [Quick Start](#-quick-start)
20
+ - [Usage Modes](#-usage-modes)
21
+ - [Manual Mode](#manual-mode)
22
+ - [Engineer Mode](#engineer-mode)
23
+ - [Agent Mode](#agent-mode)
24
+ - [Configuration](#-configuration)
25
+ - [Model Selection](#model-selection)
26
+ - [Agent Configuration](#agent-configuration)
27
+ - [SDK Selection](#sdk-selection)
28
+ - [CLI Commands](#-cli-commands)
29
+ - [Examples](#-examples)
30
+ - [Development](#-development)
31
+ - [Contributing](#-contributing)
32
+
33
+ ## ✨ Features
34
+
35
+ - 🌐 **Browser Automation**: Built on Playwright with stealth mode for realistic browsing
36
+ - 🤖 **Autonomous Agent Mode**: Fully automated browser interaction using AI agents (browser-use, stagehand)
37
+ - 📊 **HAR Recording**: Captures all network traffic in HTTP Archive format
38
+ - 🧠 **AI-Powered Generation**: Uses Claude 4.5 to analyze traffic and generate clean Python code
39
+ - 🔌 **Multi-SDK Support**: Native integration with Claude and OpenCode SDKs
40
+ - 💻 **Interactive CLI**: Minimalist terminal interface with mode cycling (Shift+Tab)
41
+ - 📦 **Production Ready**: Generated scripts include error handling, type hints, and documentation
42
+ - 💾 **Session History**: All runs saved locally with full message logs
43
+ - 💰 **Cost Tracking**: Detailed token usage and cost estimation with cache support
44
+
45
+ ### Limitations
46
+
47
+ - This tool executes code locally using Claude Code—please monitor output
48
+ - Some websites employ advanced bot-detection that may limit capture or require manual interaction
49
+
50
+ ## 🚀 Installation
51
+
52
+ ### Using uv (recommended)
53
+ ```bash
54
+ # Basic installation
55
+ uv tool install reverse-api-engineer
56
+
57
+ # With agent mode support (includes browser-use with HAR recording)
58
+ uv tool install 'reverse-api-engineer[agent]' --with 'browser-use @ git+https://github.com/browser-use/browser-use.git@49a345fb19e9f12befc5cc1658e0033873892455'
59
+ ```
60
+
61
+ ### Using pip
62
+ ```bash
63
+ # Basic installation
64
+ pip install reverse-api-engineer
65
+
66
+ # With agent mode support
67
+ pip install 'reverse-api-engineer[agent]'
68
+ pip install git+https://github.com/browser-use/browser-use.git@49a345fb19e9f12befc5cc1658e0033873892455
69
+ ```
70
+
71
+ ### Post-installation
72
+ Install Playwright browsers:
73
+ ```bash
74
+ playwright install chromium
75
+ ```
76
+
77
+ ## 🚀 Quick Start
78
+
79
+ Launch the interactive CLI:
80
+ ```bash
81
+ reverse-api-engineer
82
+ ```
83
+
84
+ The CLI has three modes (cycle with **Shift+Tab**):
85
+ - **manual**: Browser capture + AI generation
86
+ - **engineer**: Re-process existing captures
87
+ - **agent**: Autonomous AI browser agent
88
+
89
+ Example workflow:
90
+ ```bash
91
+ $ reverse-api-engineer
92
+ > fetch all apple jobs from their careers page
93
+
94
+ # Browser opens, navigate and interact
95
+ # Close browser when done
96
+ # AI generates production-ready API client
97
+
98
+ # Scripts saved to: ./scripts/apple_jobs_api/
99
+ ```
100
+
101
+ ## 📖 Usage Modes
102
+
103
+ ### Manual Mode
104
+
105
+ Full pipeline with manual browser interaction:
106
+
107
+ 1. Start the CLI: `reverse-api-engineer`
108
+ 2. Enter task description (e.g., "Fetch Apple job listings")
109
+ 3. Optionally provide starting URL
110
+ 4. Browse and interact with the website
111
+ 5. Close browser when done
112
+ 6. AI automatically generates the API client
113
+
114
+ **Output locations:**
115
+ - `~/.reverse-api/runs/scripts/{run_id}/` (permanent storage)
116
+ - `./scripts/{descriptive_name}/` (local copy with readable name)
117
+
118
+ ### Engineer Mode
119
+
120
+ Re-run AI generation on a previous capture:
121
+ ```bash
122
+ # Switch to engineer mode (Shift+Tab) and enter run_id
123
+ # Or use command line:
124
+ reverse-api-engineer engineer <run_id>
125
+ ```
126
+
127
+ ### Agent Mode
128
+
129
+ Fully automated browser interaction using AI agents:
130
+
131
+ 1. Install with agent support (see [Installation](#-installation))
132
+ 2. Start CLI and switch to agent mode (Shift+Tab)
133
+ 3. Enter task description (e.g., "Click on the first job listing")
134
+ 4. Optionally provide starting URL
135
+ 5. Agent automatically navigates and interacts
136
+ 6. HAR captured automatically
137
+ 7. Optionally generate API client
138
+
139
+ **Note:** Requires browser-use from the specific git commit shown in installation instructions (includes HAR recording support).
140
+
141
+ ## 🔧 Configuration
142
+
143
+ Settings stored in `~/.reverse-api/config.json`:
144
+ ```json
145
+ {
146
+ "model": "claude-sonnet-4-5",
147
+ "sdk": "claude",
148
+ "agent_provider": "browser-use",
149
+ "agent_model": "bu-llm",
150
+ "output_dir": null
151
+ }
152
+ ```
153
+
154
+ ### Model Selection
155
+
156
+ Choose from Claude 4.5 models for API generation:
157
+ - **Sonnet 4.5** (default): Balanced performance and cost
158
+ - **Opus 4.5**: Maximum capability for complex APIs
159
+ - **Haiku 4.5**: Fastest and most economical
160
+
161
+ Change in `/settings` or via CLI:
162
+ ```bash
163
+ reverse-api-engineer manual --model claude-sonnet-4-5
164
+ ```
165
+
166
+ ### Agent Configuration
167
+
168
+ Configure AI agents for autonomous browser automation.
169
+
170
+ **Agent Providers:**
171
+ - **browser-use** (default): Supports Browser-Use LLM, OpenAI, and Google models
172
+ - **stagehand**: Supports OpenAI and Anthropic Computer Use models
173
+
174
+ **Agent Models:**
175
+
176
+ **Browser-Use Provider:**
177
+ - `bu-llm` (default) - Requires `BROWSER_USE_API_KEY`
178
+ - `openai/gpt-4`, `openai/gpt-3.5-turbo` - Requires `OPENAI_API_KEY`
179
+ - `google/gemini-pro`, `google/gemini-1.5-pro` - Requires `GOOGLE_API_KEY`
180
+
181
+ **Stagehand Provider (Computer Use only):**
182
+ - `openai/computer-use-preview-2025-03-11` - Requires `OPENAI_API_KEY`
183
+ - `anthropic/claude-sonnet-4-5-20250929` - Requires `ANTHROPIC_API_KEY`
184
+ - `anthropic/claude-haiku-4-5-20251001` - Requires `ANTHROPIC_API_KEY`
185
+ - `anthropic/claude-opus-4-5-20251101` - Requires `ANTHROPIC_API_KEY`
186
+
187
+ **Setting API Keys:**
188
+ ```bash
189
+ export BROWSER_USE_API_KEY="your-api-key" # For Browser-Use
190
+ export OPENAI_API_KEY="your-api-key" # For OpenAI models
191
+ export ANTHROPIC_API_KEY="your-api-key" # For Anthropic models
192
+ export GOOGLE_API_KEY="your-api-key" # For Google models
193
+ ```
194
+
195
+ Change in `/settings` → "agent provider" and "agent model"
196
+
197
+ ### SDK Selection
198
+
199
+ - **Claude** (default): Direct integration with Anthropic's Claude API
200
+ - **OpenCode**: Uses OpenCode SDK (requires OpenCode running locally)
201
+
202
+ Change in `/settings` or edit `config.json` directly.
203
+
204
+ ## 💻 CLI Commands
205
+
206
+ Use these slash commands while in the CLI:
207
+ - `/settings` - Configure model, agent, SDK, and output directory
208
+ - `/history` - View past runs with costs
209
+ - `/messages <run_id>` - View detailed message logs
210
+ - `/help` - Show all commands
211
+ - `/exit` - Quit
212
+
213
+ ## 💡 Examples
214
+
215
+ ### Example: Reverse Engineering a Job Board API
216
+
217
+ ```bash
218
+ $ reverse-api-engineer
219
+ > fetch all apple jobs from their careers page
220
+
221
+ # Browser opens, you navigate and interact
222
+ # Close browser when done
223
+
224
+ # AI generates:
225
+ # - api_client.py (full API implementation)
226
+ # - README.md (documentation)
227
+ # - example_usage.py (usage examples)
228
+
229
+ # Scripts copied to: ./scripts/apple_jobs_api/
230
+ ```
231
+
232
+ Generated `api_client.py` includes:
233
+ - Authentication handling
234
+ - Clean function interfaces
235
+ - Type hints and docstrings
236
+ - Error handling
237
+ - Production-ready code
238
+
239
+ ## 🛠️ Development
240
+
241
+ ### Setup
242
+ ```bash
243
+ git clone https://github.com/kalil0321/reverse-api-engineer.git
244
+ cd reverse-api-engineer
245
+ uv sync
246
+ ```
247
+
248
+ ### Run locally
249
+ ```bash
250
+ uv run reverse-api-engineer
251
+ ```
252
+
253
+ ### Build
254
+ ```bash
255
+ ./scripts/clean_build.sh
256
+ ```
257
+
258
+ ## 🗺️ Roadmap
259
+
260
+ - ✅ **Claude SDK** - Integration with Claude Code
261
+ - ✅ **OpenCode SDK** - Integration with OpenCode
262
+ - 🔄 **Codex SDK** - Codex SDK support
263
+
264
+ ## 🔐 Requirements
265
+
266
+ - Python 3.11+
267
+ - Claude Code / OpenCode (for reverse engineering)
268
+ - Playwright browsers installed
269
+ - API key for agent mode (see [Agent Configuration](#agent-configuration))
270
+
271
+ ## 🤝 Contributing
272
+
273
+ Contributions are welcome! Please feel free to submit a Pull Request.
274
+
275
+ ## 📄 License
276
+
277
+ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "reverse-api-engineer"
3
- version = "0.2.4"
3
+ version = "0.2.6"
4
4
  description = "A tool to capture browser traffic for API reverse engineering"
5
5
  readme = "README.md"
6
6
  requires-python = ">=3.11"