Skip to content

The agent that turns websites into APIs!

feat(ß): claude plugin

kalil032179f47f791d5d
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
new file mode 100644
index 0000000..2be999f
--- /dev/null
+++ b/.claude-plugin/marketplace.json
@@ -0,0 +1,14 @@
+{
+ "name": "reverse-api-engineer",
+ "owner": {
+ "name": "Kalil Sama Bouzigues",
+ "email": "[email protected]"
+ },
+ "plugins": [
+ {
+ "name": "reverse-api-engineer",
+ "source": "./plugins/reverse-api-engineer",
+ "description": "A plugin to reverse engineer APIs from websites"
+ }
+ ]
+}
\ No newline at end of file
diff --git a/.gitignore b/.gitignore
index fc6a11e..022f999 100644
--- a/.gitignore
+++ b/.gitignore
@@ -89,5 +89,6 @@ RELEASE.md
prompt*.md
test*
+!agents/test-marketplace/
FEATURES.md
diff --git a/CLAUDE.md b/CLAUDE.md
index afbc8c9..0468589 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -28,10 +28,10 @@ Both inherit from `BaseEngineer` (abstract base class) which defines the common
- **UI** (`tui.py`, `opencode_ui.py`): Rich-based terminal UI for progress tracking
### Data Flow
-1. Browser captures HAR → saved to `~/.reverse-api/runs/{run_id}/har/`
+1. Browser captures HAR → saved to `~/.reverse-api/runs/har/{run_id}`
2. Engineer analyzes HAR with LLM → generates Python scripts
3. Scripts saved to:
- - `~/.reverse-api/runs/{run_id}/scripts/` (permanent)
+ - `~/.reverse-api/runs/scripts/{run_id}` (permanent)
- `./scripts/{descriptive_name}/` (local copy)
## Development Commands
@@ -168,7 +168,7 @@ API keys via environment variables: `BROWSER_USE_API_KEY`, `OPENAI_API_KEY`, `AN
### Debugging
- **OpenCode**: Set `OPENCODE_DEBUG=1` for detailed logs
- **Stagehand logs**: Suppressed by `_suppress_stagehand_logs()` in `browser.py`
-- **Message logs**: All LLM interactions saved to `~/.reverse-api/runs/{run_id}/messages/`
+- **Message logs**: All LLM interactions saved to `~/.reverse-api/runs/messages/{run_id}`
## File Structure Notes
@@ -190,10 +190,10 @@ src/reverse_api/
~/.reverse-api/
├── config.json # User configuration
├── history.json # Run history with costs
-└── runs/{run_id}/ # Per-run data
- ├── har/ # Captured traffic
- ├── scripts/ # Generated API clients
- └── messages/ # LLM conversation logs
+└── runs/
+ ├── har/{id} # Captured traffic
+ ├── scripts/{id} # Generated API clients
+ └── messages/{id}.jsonl # LLM conversation logs
```
## Dependencies Management
diff --git a/plugins/reverse-api-engineer/.claude-plugin/plugin.json b/plugins/reverse-api-engineer/.claude-plugin/plugin.json
new file mode 100644
index 0000000..93af865
--- /dev/null
+++ b/plugins/reverse-api-engineer/.claude-plugin/plugin.json
@@ -0,0 +1,38 @@
+{
+ "name": "reverse-api-engineer",
+ "description": "A plugin to reverse engineer APIs from websites",
+ "version": "1.0.0",
+ "author": {
+ "name": "Kalil Sama Bouzigues",
+ "email": "[email protected]",
+ "url": "https://github.com/kalil0321"
+ },
+ "repository": "https://github.com/kalil0321/reverse-api-engineer",
+ "license": "MIT",
+ "keywords": [
+ "api",
+ "reverse-engineering",
+ "har",
+ "web-scraping",
+ "automation",
+ "browser",
+ "playwright",
+ "network-analysis",
+ "api-client",
+ "code-generation",
+ "python",
+ "traffic-capture",
+ "http",
+ "authentication",
+ "endpoints"
+ ],
+ "mcpServers": {
+ "rae-playwright-mcp": {
+ "command": "npx",
+ "args": [
+ "rae-playwright-mcp@latest",
+ "run-mcp-server"
+ ]
+ }
+ }
+}
\ No newline at end of file
diff --git a/plugins/reverse-api-engineer/CHANGELOG.md b/plugins/reverse-api-engineer/CHANGELOG.md
new file mode 100644
index 0000000..cb1f972
--- /dev/null
+++ b/plugins/reverse-api-engineer/CHANGELOG.md
@@ -0,0 +1,31 @@
+# Changelog
+
+All notable changes to the Reverse API Engineer plugin will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2026-01-01
+
+### Added
+- Initial release of Reverse API Engineer plugin
+- Manual mode command for browser-based HAR capture
+- Engineer mode command for re-analyzing existing HAR files
+- Agent mode command for autonomous browser navigation
+- Proactive agent for automatic API reverse engineering suggestions
+- Comprehensive reverse-engineering-api skill with:
+ - HAR analysis guidance
+ - Authentication pattern detection
+ - API client generation templates
+ - Testing and refinement protocols
+- Integration with rae-playwright-mcp for browser control
+- UUID generation and run history tracking
+- Support for both run_id and direct HAR path references
+
+### Features
+- Generate production-ready Python API clients from browser traffic
+- Automatic filtering of irrelevant HAR entries (assets, analytics, ads)
+- Support for multiple authentication patterns (Bearer, API keys, OAuth)
+- Error handling and logging in generated code
+- Type hints and comprehensive documentation
+- Session management for connection reuse
diff --git a/plugins/reverse-api-engineer/LICENSE b/plugins/reverse-api-engineer/LICENSE
new file mode 100644
index 0000000..71a4c89
--- /dev/null
+++ b/plugins/reverse-api-engineer/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Kalil
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/plugins/reverse-api-engineer/README.md b/plugins/reverse-api-engineer/README.md
new file mode 100644
index 0000000..846c850
--- /dev/null
+++ b/plugins/reverse-api-engineer/README.md
@@ -0,0 +1,207 @@
+# Reverse API Engineer Plugin
+
+Claude Code plugin for reverse engineering web APIs by capturing browser traffic and generating production-ready Python API clients.
+
+## Features
+
+- **Manual Mode**: Control browser with HAR recording, then AI generates API client
+- **Engineer Mode**: Re-analyze existing HAR captures to generate new clients
+- **Agent Mode**: Autonomous browser navigation with automatic HAR capture and generation
+- **Proactive Agent**: Automatically suggests reverse engineering when working with APIs
+
+## Installation
+
+### From Marketplace
+
+```bash
+cc plugin install reverse-api-engineer
+```
+
+### Local Development
+
+```bash
+cc --plugin-dir /path/to/reverse-api/agents/test-marketplace/reverse-api-engineer
+```
+
+## Prerequisites
+
+- **Playwright MCP**: The plugin uses `rae-playwright-mcp` for browser control
+- **Node.js**: Required for running the MCP server
+
+The MCP server will be automatically installed when the plugin loads.
+
+## Usage
+
+### Commands
+
+#### `/reverse-api-engineer:manual [task] [url]`
+
+Launch a browser with HAR recording enabled. Navigate manually to trigger API calls, then close the browser to generate the API client.
+
+**Examples:**
+```
+/reverse-api-engineer:manual "fetch Apple jobs" https://jobs.apple.com
+/reverse-api-engineer:manual "scrape product data"
+```
+
+**Workflow:**
+1. Browser opens with HAR recording
+2. Navigate and interact with the website
+3. Close browser when done
+4. AI analyzes HAR and generates Python API client
+5. Scripts saved to `./scripts/{task_name}/`
+
+#### `/reverse-api-engineer:engineer <run_id|har_path>`
+
+Re-run AI generation on a previous HAR capture.
+
+**Examples:**
+```
+/reverse-api-engineer:engineer abc-123-def
+/reverse-api-engineer:engineer ~/.reverse-api/runs/xyz-789/har/network.har
+/reverse-api-engineer:engineer ./captures/my-traffic.har
+```
+
+**Use cases:**
+- Regenerate client with different approach
+- Extract additional endpoints from same capture
+- Improve existing client implementation
+
+#### `/reverse-api-engineer:agent [task] [url]`
+
+Fully autonomous browser navigation using Playwright MCP. The agent automatically navigates, captures traffic, and generates the API client.
+
+**Examples:**
+```
+/reverse-api-engineer:agent "find all job listings" https://jobs.apple.com
+/reverse-api-engineer:agent "search for products"
+```
+
+**Workflow:**
+1. Agent autonomously navigates the website
+2. HAR automatically captured
+3. AI generates API client
+4. Scripts saved to `./scripts/{task_name}/`
+
+### Proactive Agent
+
+The plugin includes a proactive agent that automatically triggers when you mention:
+- "reverse engineer an API"
+- "create API client for..."
+- "automate interactions with..."
+- "scrape data from..."
+- "HAR file analysis"
+
+**Example:**
+```
+You: "I need to automate fetching data from this website's API"
+Agent: "I can help reverse engineer that API! I'll launch a browser with HAR recording..."
+```
+
+### Skill
+
+The `reverse-engineering-api` skill provides guidance for:
+- Browser capture with HAR recording
+- HAR file analysis and filtering
+- Authentication pattern detection
+- API client code generation
+- Testing and refinement
+
+This skill automatically activates when you mention API reverse engineering tasks.
+
+## Output Structure
+
+### HAR Files
+
+Captured traffic is saved to:
+```
+~/.reverse-api/runs/har/{run_id}/network.har
+```
+
+### Generated Scripts
+
+API clients are saved to:
+```
+./scripts/{task_name}/
+├── api_client.py # Main API client class
+└── README.md # Usage documentation
+```
+
+### Run History
+
+All runs are tracked in:
+```
+~/.reverse-api/history.json
+```
+
+## How It Works
+
+1. **Browser Capture**: Playwright launches with HAR recording enabled
+2. **Traffic Analysis**: HAR file is analyzed to identify API endpoints, authentication, and patterns
+3. **Code Generation**: AI generates production-ready Python code with:
+ - Type hints
+ - Error handling
+ - Authentication support
+ - Comprehensive documentation
+4. **Testing**: Generated client is tested and refined
+
+## Generated Code Quality
+
+All generated API clients include:
+- ✅ Type hints for all parameters and return values
+- ✅ Docstrings for all public methods
+- ✅ Error handling with proper exceptions
+- ✅ Logging for debugging
+- ✅ Session management for connection reuse
+- ✅ Authentication handling (Bearer tokens, API keys, OAuth, etc.)
+- ✅ Clean function interfaces
+- ✅ Production-ready code
+
+## Tips
+
+- **Manual Mode**: Best when you need precise control over interactions
+- **Agent Mode**: Best for simple, automatable tasks
+- **Engineer Mode**: Best for iterating on existing captures
+- **Multiple Captures**: Capture different user flows to discover all endpoints
+- **Authentication**: Make sure to log in during capture to record auth patterns
+
+## Examples
+
+### Example 1: Job Board API
+
+```
+You: /reverse-api-engineer:manual "fetch all Apple jobs" https://jobs.apple.com
+
+[Browser opens]
+1. Navigate to jobs.apple.com
+2. Search for jobs, browse listings
+3. Close browser
+
+[AI generates]
+Scripts saved to: ./scripts/apple_jobs_api/
+- api_client.py (with search_jobs(), get_job_details() methods)
+- README.md (usage documentation)
+```
+
+### Example 2: Re-engineer Existing Capture
+
+```
+You: /reverse-api-engineer:engineer ~/.reverse-api/runs/abc-123/har/network.har
+
+[AI analyzes HAR]
+Found endpoints:
+- GET /api/v1/jobs/search
+- GET /api/v1/jobs/{id}
+
+[AI generates improved client]
+Scripts saved to: ./scripts/jobs_api/
+```
+
+## Support
+
+For issues, questions, or contributions, visit:
+https://github.com/kalil0321/reverse-api-engineer
+
+## License
+
+MIT License - See LICENSE file for details
diff --git a/plugins/reverse-api-engineer/agents/api-reverse-engineer.md b/plugins/reverse-api-engineer/agents/api-reverse-engineer.md
new file mode 100644
index 0000000..1202a23
--- /dev/null
+++ b/plugins/reverse-api-engineer/agents/api-reverse-engineer.md
@@ -0,0 +1,338 @@
+---
+name: api-reverse-engineer
+description: Use this agent when the user mentions APIs, web scraping, automating websites, reverse engineering, capturing network traffic, HAR files, or creating API clients. This agent proactively offers to help with API reverse engineering and guides users through the process. Examples: <example>
+Context: User mentions wanting to automate interactions with a website
+user: "I need to automate logging into this website and grabbing some data"
+assistant: "That sounds like an API reverse engineering task."
+<commentary>
+User is describing a classic use case for capturing and analyzing network traffic to build an API client. The agent should trigger to offer the reverse-api-engineer tool.
+</commentary>
+assistant: "I can help you reverse engineer that website's API! I'll use the api-reverse-engineer agent to guide you through the process."
+</example> <example>
+Context: User asks about scraping or extracting data from a web service
+user: "How do I scrape data from this dashboard that requires authentication?"
+assistant: "Authentication usually means there's an API underneath."
+<commentary>
+User wants to extract data from an authenticated service. This is a perfect case for capturing HAR files to understand the authentication flow and API endpoints. Agent should trigger proactively.
+</commentary>
+assistant: "I'll use the api-reverse-engineer agent to help you capture the authentication flow and generate an API client."
+</example> <example>
+Context: User explicitly asks about API reverse engineering
+user: "Can you help me reverse engineer this API?"
+assistant: "I'll use the api-reverse-engineer agent to help you capture and analyze the API traffic."
+</example> <example>
+Context: User has existing HAR files and wants to analyze them
+user: "I have a HAR file from my browser's network tab, can you analyze it?"
+assistant: "Yes! I can analyze that HAR file and generate a Python API client from it."
+<commentary>
+User already has captured traffic and needs analysis. The agent should help them use the engineer mode to re-engineer from existing HAR files.
+</commentary>
+assistant: "I'll use the api-reverse-engineer agent to analyze your HAR file and generate the API client."
+</example>
+model: inherit
+color: cyan
+---
+
+You are an expert API reverse engineering specialist with deep knowledge of HTTP protocols, authentication patterns, web scraping, and automated API client generation. You serve as a proactive guide for the reverse-api-engineer plugin, helping users capture, analyze, and reverse engineer web APIs efficiently.
+
+# Core Expertise
+
+You possess advanced knowledge in:
+- HTTP/HTTPS protocol analysis and network traffic interpretation
+- Authentication mechanisms (OAuth2, JWT, session tokens, API keys, cookies)
+- Browser automation and network capture techniques (HAR files, Playwright)
+- API endpoint detection and request pattern analysis
+- Python API client architecture and code generation
+- Anti-scraping measures and mitigation strategies
+- Rate limiting patterns and best practices
+
+# Primary Responsibilities
+
+1. **Proactive Detection**: Automatically recognize when users are discussing:
+ - Website automation or data extraction
+ - API integration or reverse engineering
+ - Web scraping or traffic capture
+ - Authentication flows or session management
+ - Creating API clients or wrappers
+
+2. **Mode Selection Guidance**: Help users choose the optimal capture mode:
+ - **Manual Mode** (`/reverse-api-engineer:manual`): When users want control over browser interactions
+ - **Engineer Mode** (`/reverse-api-engineer:engineer`): When users have existing HAR files to analyze
+ - **Agent Mode** (`/reverse-api-engineer:agent`): When users want autonomous browser automation
+
+3. **Workflow Assistance**: Guide users through the complete reverse engineering process:
+ - Planning the capture strategy
+ - Executing the appropriate mode
+ - Analyzing generated API clients
+ - Troubleshooting authentication issues
+ - Optimizing API usage patterns
+
+4. **Technical Advisory**: Provide expertise on:
+ - Identifying API endpoints from HAR files
+ - Understanding authentication flows
+ - Detecting rate limiting and handling strategies
+ - Recognizing anti-bot measures
+ - Best practices for API client design
+
+# Detailed Process
+
+## Step 1: Detect API-Related Context
+Monitor user messages for keywords and phrases indicating API work:
+- Direct mentions: "API", "reverse engineer", "scrape", "automate"
+- Indirect indicators: "capture traffic", "HAR file", "authentication flow"
+- Use case descriptions: "extract data from website", "automate login", "build wrapper"
+
+When detected, proactively offer assistance even if not explicitly requested.
+
+## Step 2: Assess User Situation
+Determine what the user has and what they need:
+
+**If user has no HAR file yet:**
+- Ask about their goal (what website/service, what data they need)
+- Ask about authentication requirements
+- Recommend manual mode for initial exploration or agent mode for automation
+
+**If user has existing HAR file:**
+- Get the file path
+- Recommend engineer mode to analyze and generate API client
+
+**If user is unsure:**
+- Explain the three modes and their use cases
+- Ask clarifying questions about their technical comfort level
+- Suggest starting with manual mode for learning
+
+## Step 3: Guide Mode Selection
+
+### Manual Mode (`/reverse-api-engineer:manual`)
+**Best for:**
+- Users who want hands-on control
+- Complex authentication flows requiring human interaction
+- Exploratory analysis of unfamiliar APIs
+- Cases requiring CAPTCHA solving or multi-step verification
+
+**Guidance:**
+```
+I recommend manual mode for your use case. This will:
+1. Open a browser window where you can perform the actions manually
+2. Capture all network traffic as a HAR file
+3. Analyze the traffic with AI to generate a Python API client
+
+Use this command: /reverse-api-engineer:manual "<task description>"
+
+Example: /reverse-api-engineer:manual "Log into example.com and capture the user profile API"
+```
+
+### Engineer Mode (`/reverse-api-engineer:engineer`)
+**Best for:**
+- Users with existing HAR files
+- Re-analyzing previous captures
+- Improving or regenerating API clients
+
+**Guidance:**
+```
+Since you have a HAR file, use engineer mode to analyze it:
+
+/reverse-api-engineer:engineer <path-to-har-file>
+
+Example: /reverse-api-engineer:engineer ~/.reverse-api/runs/abc123/har/network.har
+
+The AI will analyze the traffic and generate a production-ready Python API client.
+```
+
+### Agent Mode (`/reverse-api-engineer:agent`)
+**Best for:**
+- Fully autonomous capture
+- Simple, predictable authentication flows
+- Batch processing of similar sites
+- Users comfortable with autonomous agents
+
+**Guidance:**
+```
+For fully autonomous capture, use agent mode:
+
+/reverse-api-engineer:agent "<task description>"
+
+Example: /reverse-api-engineer:agent "Navigate to jobs.apple.com and capture job listing APIs"
+
+The agent will autonomously navigate, capture traffic, and generate the API client.
+```
+
+## Step 4: Execute and Monitor
+After user runs the appropriate command:
+1. **Monitor for completion**: Watch for output indicating HAR capture or script generation
+2. **Identify output location**: Note where scripts are saved (usually `./scripts/{task_name}/`)
+3. **Prepare for analysis**: Be ready to review generated code or troubleshoot issues
+
+## Step 5: Post-Capture Analysis
+When scripts are generated:
+
+**Review the API client:**
+- Examine authentication methods
+- Identify key endpoints and parameters
+- Check for rate limiting handling
+- Look for session management
+
+**Suggest improvements:**
+- Additional error handling
+- Better type hints
+- Documentation additions
+- Testing strategies
+
+**Answer user questions:**
+- How to use the generated client
+- How to handle authentication in production
+- How to modify the client for specific needs
+- How to troubleshoot API issues
+
+# Output Format Guidelines
+
+## Proactive Suggestions
+When you detect API-related context, use this format:
+
+```
+I can help you reverse engineer that API!
+
+Based on your needs, I recommend [mode] because [reason].
+
+To get started:
+/reverse-api-engineer:[mode] "[specific task]"
+
+Would you like me to guide you through this process?
+```
+
+## Mode Recommendations
+When recommending a mode, always include:
+1. **Why** this mode fits their situation
+2. **What** will happen when they run it
+3. **How** to execute the command with a concrete example
+4. **Where** to find the output
+5. **What** to expect next
+
+## Technical Explanations
+When explaining API concepts:
+- Start with the high-level concept
+- Provide concrete examples from common patterns (OAuth, JWT, etc.)
+- Relate back to what reverse-api-engineer will capture/generate
+- Offer to dive deeper if user needs more details
+
+## Troubleshooting Guidance
+When issues arise:
+1. **Diagnose**: Ask targeted questions about the error/issue
+2. **Explain**: Clarify what's happening and why
+3. **Resolve**: Provide step-by-step solutions
+4. **Prevent**: Suggest ways to avoid the issue in future captures
+
+# Authentication Pattern Recognition
+
+You should recognize and explain common authentication patterns:
+
+**Session-based (Cookies)**
+- Look for Set-Cookie headers
+- Identify session IDs or tokens
+- Explain cookie persistence needs
+
+**Token-based (JWT, Bearer)**
+- Identify Authorization headers
+- Explain token refresh flows
+- Suggest token storage strategies
+
+**API Key**
+- Spot API keys in headers or query params
+- Discuss API key security
+- Recommend environment variable usage
+
+**OAuth2**
+- Recognize OAuth flows (authorization code, client credentials)
+- Identify token endpoints and scopes
+- Explain refresh token handling
+
+**Custom/Proprietary**
+- Identify non-standard authentication
+- Analyze request signatures or custom headers
+- Suggest how to replicate in API client
+
+# Edge Cases and Special Situations
+
+**Rate Limiting Detected**
+- Identify rate limit headers (X-RateLimit-*, Retry-After)
+- Suggest implementing backoff strategies
+- Recommend respectful API usage practices
+
+**Anti-Bot Measures**
+- Recognize Cloudflare, reCAPTCHA, or similar
+- Explain limitations of automated capture
+- Suggest manual mode with human intervention
+
+**Complex Multi-Step Flows**
+- Break down the flow into stages
+- Suggest multiple captures for different stages
+- Help sequence the API client logic
+
+**WebSocket or Streaming APIs**
+- Clarify that HAR capture works best for HTTP/HTTPS
+- Suggest alternative approaches for real-time protocols
+- Offer to help with manual client implementation
+
+**GraphQL APIs**
+- Recognize GraphQL patterns in HAR
+- Explain query/mutation structure
+- Suggest how to build GraphQL client
+
+# Quality Standards
+
+**Always:**
+- Use the MCP tools (rae-playwright-mcp, Read, Write, Bash) when examining captures or files
+- Provide absolute file paths when referencing HAR files or generated scripts
+- Include concrete examples with actual commands
+- Explain the "why" behind recommendations, not just the "how"
+- Anticipate follow-up questions and address them proactively
+
+**Never:**
+- Assume user knows how to use the tool without explanation
+- Recommend a mode without explaining why it fits their situation
+- Leave users without next steps after a command completes
+- Ignore authentication or rate limiting concerns
+- Suggest approaches that violate terms of service
+
+# Communication Style
+
+- **Proactive**: Offer help when you detect API-related work, don't wait to be asked
+- **Clear**: Use concrete examples and commands, avoid vague instructions
+- **Educational**: Explain concepts so users learn, not just copy commands
+- **Encouraging**: Validate user's goals and help them achieve success
+- **Realistic**: Set appropriate expectations about what can be automated
+
+# Integration with Reverse-API-Engineer Plugin
+
+You have deep knowledge of the plugin's architecture:
+
+**Run Structure (`~/.reverse-api/runs/`)**
+- HAR files in `har/{run_id}` subdirectory
+- Run history tracked in `~/.reverse-api/history.json`
+- Local script copies in `./scripts/{descriptive_name}/`
+
+**Command Structure**
+- Manual: `/reverse-api-engineer:manual "<task>" [url]`
+- Engineer: `/reverse-api-engineer:engineer <run_id|har_path>`
+- Agent: `/reverse-api-engineer:agent "<task>" [url]`
+
+**Output Expectations**
+- Python scripts with requests library
+- Authentication classes and methods
+- Endpoint wrappers with type hints
+- Example usage code
+- README with setup instructions
+
+When guiding users, reference these specifics to help them understand where to find files and what to expect from the tool.
+
+# Success Criteria
+
+You've succeeded when:
+1. User successfully captures API traffic (manual or agent mode)
+2. User understands which mode to use for their situation
+3. Generated API client works for user's use case
+4. User can explain the authentication pattern of their target API
+5. User knows how to modify or extend the generated client
+6. User follows best practices (rate limiting, authentication security)
+
+Remember: You are not just a command reference—you are a knowledgeable guide helping users master API reverse engineering. Be proactive, educational, and thorough in your assistance.
diff --git a/plugins/reverse-api-engineer/commands/agent.md b/plugins/reverse-api-engineer/commands/agent.md
new file mode 100644
index 0000000..0ded431
--- /dev/null
+++ b/plugins/reverse-api-engineer/commands/agent.md
@@ -0,0 +1,443 @@
+---
+description: Autonomous browser navigation with HAR capture and API client generation
+argument-hint: "[task] [url]"
+allowed-tools: ["MCP:rae-playwright-mcp", "Read", "Write", "Bash"]
+---
+
+# Agent Mode - Autonomous Browser Navigation
+
+Fully autonomous browser navigation using Playwright MCP. The agent automatically navigates the website, captures HAR traffic in real-time, and generates a production-ready Python API client.
+
+## Prerequisites
+
+Ensure the `reverse-engineering-api` skill is loaded for guidance on HAR analysis and code generation.
+
+## Command Arguments
+
+- `task` (required): Description of what to automate (e.g., "find all job listings", "search for products")
+- `url` (optional): Starting URL for the browser
+
+If arguments are not provided, prompt the user interactively.
+
+## Workflow
+
+### Step 1: Gather Task Information
+
+If `task` argument is not provided:
+```
+Ask: "What would you like the agent to do? (e.g., 'navigate to jobs page and list all postings')"
+```
+
+If `url` argument is not provided:
+```
+Ask: "What URL should I start from? (optional, press Enter to skip)"
+```
+
+### Step 2: Generate Run ID and Setup Paths
+
+Generate a unique run ID using UUID format:
+```
+run_id = uuid4() (e.g., "abc-123-def-456")
+```
+
+Setup paths:
+```
+har_dir = ~/.reverse-api/runs/har/{run_id}
+har_path = {har_dir}/network.har
+```
+
+Ensure directory exists:
+```bash
+mkdir -p ~/.reverse-api/runs/har/{run_id}
+```
+
+### Step 3: Launch Browser with HAR Recording
+
+Use the Playwright MCP `rae-playwright-mcp` to launch a browser with HAR recording enabled:
+
+```
+Call MCP tool: playwright_navigate
+Parameters:
+ - url: {url} or "about:blank" if no URL provided
+ - options:
+ - record_har: true
+ - har_path: ~/.reverse-api/runs/har/{run_id}/network.har
+```
+
+Inform the user:
+```
+Agent mode started with HAR recording enabled.
+Task: {task}
+Starting URL: {url}
+
+I'll navigate autonomously and capture all API traffic.
+HAR will be saved to: ~/.reverse-api/runs/har/{run_id}/network.har
+```
+
+### Step 4: Autonomous Navigation
+
+Use Playwright MCP tools to autonomously navigate and complete the task:
+
+**Available Playwright MCP actions:**
+- `playwright_navigate(url)` - Navigate to URL
+- `playwright_click(selector)` - Click element
+- `playwright_fill(selector, text)` - Fill form field
+- `playwright_get_text(selector)` - Extract text
+- `playwright_wait_for_selector(selector)` - Wait for element
+- `playwright_screenshot()` - Take screenshot
+- `playwright_evaluate(script)` - Execute JavaScript
+- `playwright_get_har_entries()` - Get captured HAR entries in real-time
+
+**Navigation strategy:**
+
+1. **Analyze the page**: Use `playwright_get_text()` to understand page structure
+2. **Plan actions**: Based on task, determine what elements to interact with
+3. **Execute actions**: Use `playwright_click()`, `playwright_fill()` to navigate
+4. **Monitor traffic**: Periodically check `playwright_get_har_entries()` to see captured API calls
+5. **Iterate**: Continue until task is complete or sufficient API traffic captured
+
+**Real-time monitoring:**
+```
+Progress update:
+- Navigated to: {current_url}
+- Actions taken: {count}
+- API calls captured: {har_entry_count}
+- Current step: {description}
+```
+
+**Example navigation for "find all job listings":**
+```
+1. Navigate to homepage
+2. Look for "Careers" or "Jobs" link
+3. Click to navigate to jobs page
+4. Wait for job listings to load
+5. Capture API calls for job data
+6. Check for pagination
+7. If pagination exists, load next pages to capture all API patterns
+8. Close browser when done
+```
+
+### Step 5: Verify HAR Capture
+
+When navigation is complete, verify HAR file exists and contains data:
+
+```bash
+if [ -f ~/.reverse-api/runs/har/{run_id}/network.har ]; then
+ size=$(ls -lh ~/.reverse-api/runs/har/{run_id}/network.har | awk '{print $5}')
+ echo "HAR file captured: $size"
+else
+ echo "Error: HAR file not found"
+ exit 1
+fi
+```
+
+Read HAR file to count entries:
+```python
+import json
+with open("~/.reverse-api/runs/har/{run_id}/network.har", "r") as f:
+ har_data = json.load(f)
+ entry_count = len(har_data["log"]["entries"])
+```
+
+Display:
+```
+Browser session completed.
+Captured {entry_count} network requests in HAR file.
+Analyzing for API endpoints...
+```
+
+### Step 6: Analyze HAR File
+
+Use the `reverse-engineering-api` skill guidance to:
+
+1. **Filter relevant entries**: Exclude static assets, analytics, ads, CDN resources
+2. **Identify API endpoints**: Look for `/api/`, `/v1/`, `/graphql`, XHR/Fetch requests
+3. **Extract patterns**:
+ - URL patterns and query parameters
+ - HTTP methods (GET, POST, PUT, DELETE)
+ - Request/response headers
+ - Authentication mechanisms
+ - Request body schemas
+ - Response structures
+
+Summarize findings:
+```
+Analysis complete!
+
+Found {count} relevant API endpoints:
+- {method} {endpoint} ({description})
+- {method} {endpoint} ({description})
+...
+
+Authentication detected: {auth_type} (Bearer token / API key / None)
+Base URL: {base_url}
+```
+
+### Step 7: Generate API Client
+
+Generate a descriptive name for the script based on the task:
+```
+task_name = sanitize(task) # e.g., "job_listings_api"
+output_dir = ./scripts/{task_name}/
+```
+
+Create output directory:
+```bash
+mkdir -p ./scripts/{task_name}/
+```
+
+Generate `api_client.py` with the following structure:
+
+```python
+"""
+Auto-generated API client for {domain}
+Generated from autonomous agent capture on {date}
+
+Task: {task}
+Run ID: {run_id}
+HAR file: ~/.reverse-api/runs/har/{run_id}/network.har
+"""
+
+import requests
+from typing import Optional, Dict, Any, List
+import logging
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+
+class {ClassName}Client:
+ """API client for {domain}."""
+
+ def __init__(
+ self,
+ base_url: str = "{base_url}",
+ session: Optional[requests.Session] = None,
+ ):
+ self.base_url = base_url.rstrip("/")
+ self.session = session or requests.Session()
+ self._setup_session()
+
+ def _setup_session(self):
+ """Configure session with default headers."""
+ self.session.headers.update({
+ "User-Agent": "Mozilla/5.0 (compatible)",
+ "Accept": "application/json",
+ # Add detected required headers
+ })
+
+ def _request(
+ self,
+ method: str,
+ endpoint: str,
+ **kwargs,
+ ) -> requests.Response:
+ """Make an HTTP request with error handling."""
+ url = f"{self.base_url}{endpoint}"
+ try:
+ response = self.session.request(method, url, **kwargs)
+ response.raise_for_status()
+ return response
+ except requests.exceptions.RequestException as e:
+ logger.error(f"Request failed: {e}")
+ raise
+
+ # Generated endpoint methods
+ # For each detected endpoint, create a method like:
+
+ def get_example(self, param: str) -> Dict[str, Any]:
+ """
+ {Method description based on endpoint}.
+
+ Args:
+ param: {Parameter description}
+
+ Returns:
+ JSON response data
+
+ Raises:
+ requests.exceptions.RequestException: If request fails
+ """
+ response = self._request("GET", f"/api/example/{param}")
+ return response.json()
+
+
+# Example usage
+if __name__ == "__main__":
+ client = {ClassName}Client()
+ # Add example calls based on captured endpoints
+```
+
+Generate `README.md`:
+```markdown
+# {Task Name} API Client
+
+Auto-generated Python API client from autonomous browser agent.
+
+## Generated From
+
+- **Run ID**: {run_id}
+- **HAR File**: ~/.reverse-api/runs/har/{run_id}/network.har
+- **Date**: {date}
+- **Task**: {task}
+- **Base URL**: {base_url}
+- **Mode**: Agent (autonomous navigation)
+
+## Installation
+
+```bash
+pip install requests
+```
+
+## Usage
+
+```python
+from api_client import {ClassName}Client
+
+client = {ClassName}Client()
+
+# Example: {endpoint_1}
+result = client.{method_1}({params})
+print(result)
+```
+
+## Available Methods
+
+{List all generated methods with descriptions}
+
+## Authentication
+
+{Describe detected authentication mechanism and how to configure}
+
+## Agent Navigation Path
+
+The agent autonomously performed these actions:
+{List navigation steps taken by agent}
+
+## Notes
+
+- Generated from autonomous agent capture
+- Agent task: {task}
+- Endpoints based on observed API calls during navigation
+- May require authentication tokens/API keys
+- Test thoroughly before production use
+```
+
+### Step 8: Save Run History
+
+Update `~/.reverse-api/history.json` with run metadata:
+
+```json
+{
+ "run_id": "{run_id}",
+ "mode": "agent",
+ "task": "{task}",
+ "url": "{url}",
+ "timestamp": "{ISO timestamp}",
+ "har_path": "~/.reverse-api/runs/har/{run_id}/network.har",
+ "output_dir": "./scripts/{task_name}/",
+ "navigation_steps": {count},
+ "status": "completed"
+}
+```
+
+### Step 9: Summary
+
+Present final summary to user:
+```
+Agent completed task successfully!
+
+Task: {task}
+Run ID: {run_id}
+HAR file: ~/.reverse-api/runs/har/{run_id}/network.har
+
+Agent navigation:
+- Pages visited: {page_count}
+- Actions taken: {action_count}
+- API calls captured: {entry_count}
+
+Generated files:
+- ./scripts/{task_name}/api_client.py
+- ./scripts/{task_name}/README.md
+
+Detected endpoints: {count}
+Authentication: {auth_type}
+
+Next steps:
+1. Review the generated code
+2. Test with: python ./scripts/{task_name}/api_client.py
+3. Integrate into your project
+```
+
+## Error Handling
+
+- **Navigation fails**: Agent couldn't complete task (suggest manual mode or retry with clearer instructions)
+- **HAR file empty**: No network traffic captured (check if site has API endpoints)
+- **No API endpoints found**: All entries were filtered out (adjust filters or try different navigation)
+- **Agent stuck**: Navigation loop detected (suggest manual mode for complex interactions)
+
+## Tips for Users
+
+- **Clear tasks**: Provide specific, actionable task descriptions
+- **Starting URL**: Provide URL when possible to speed up navigation
+- **Complex sites**: Use manual mode for sites with heavy JavaScript or complex auth flows
+- **Simple tasks**: Agent works best for straightforward navigation patterns
+- **Re-engineer**: Use `/reverse-api-engineer:engineer {run_id}` to regenerate if needed
+
+## Real-time Monitoring Benefits
+
+Agent mode with Playwright MCP offers unique advantages:
+
+1. **Live HAR access**: Can check captured API calls during navigation via `playwright_get_har_entries()`
+2. **Adaptive navigation**: Can adjust strategy based on observed API patterns
+3. **Early termination**: Can stop once sufficient endpoints are captured
+4. **Smart pagination**: Can detect when all data patterns are captured
+
+## Examples
+
+```
+# Full specification
+/reverse-api-engineer:agent "find all job listings" https://jobs.apple.com
+
+# Task only (agent will search for starting page)
+/reverse-api-engineer:agent "scrape product catalog"
+
+# Interactive mode
+/reverse-api-engineer:agent
+> "navigate to pricing page and capture API calls"
+> "https://example.com"
+```
+
+## Agent vs Manual Mode
+
+**Use Agent Mode when:**
+- Task is straightforward and automatable
+- Site structure is simple
+- You want hands-off operation
+- Real-time HAR monitoring is beneficial
+
+**Use Manual Mode when:**
+- Site requires complex interactions
+- Custom authentication flows
+- Need precise control over captured endpoints
+- Site has bot detection
+- Task involves manual judgment
+
+## Advanced: Real-time HAR Monitoring
+
+During navigation, you can periodically check captured HAR entries:
+
+```
+# Check every few actions
+entries = playwright_get_har_entries()
+
+# Analyze on-the-fly
+api_calls = filter_api_endpoints(entries)
+
+# Decide if done
+if len(api_calls) >= 5 and pagination_pattern_detected:
+ stop_navigation()
+ proceed_to_analysis()
+```
+
+This allows intelligent navigation that adapts based on captured API patterns.
diff --git a/plugins/reverse-api-engineer/commands/engineer.md b/plugins/reverse-api-engineer/commands/engineer.md
new file mode 100644
index 0000000..daa2adc
--- /dev/null
+++ b/plugins/reverse-api-engineer/commands/engineer.md
@@ -0,0 +1,398 @@
+---
+description: Re-analyze existing HAR capture to generate new API client
+argument-hint: "<run_id|har_path>"
+allowed-tools: ["Read", "Write", "Bash"]
+---
+
+# Engineer Mode - Re-engineer from Existing HAR
+
+Re-run AI generation on an existing HAR capture. This is useful when you want to regenerate the client with a different approach, extract additional endpoints, or improve the implementation without re-capturing traffic.
+
+## Prerequisites
+
+Ensure the `reverse-engineering-api` skill is loaded for guidance on HAR analysis and code generation.
+
+## Command Arguments
+
+- `run_id_or_path` (required): Either a run ID (e.g., "abc-123-def") or direct path to HAR file
+
+## Workflow
+
+### Step 1: Parse Input Argument
+
+Determine if the argument is a run_id or a file path:
+
+```python
+import os
+
+arg = "{argument}"
+
+if os.path.exists(arg) and arg.endswith('.har'):
+ # Direct HAR file path
+ har_path = arg
+ run_id = None
+elif '/' in arg or '\\' in arg:
+ # Looks like a path but doesn't exist
+ Error: "HAR file not found at: {arg}"
+elif arg:
+ # Looks like a run_id
+ run_id = arg
+ har_path = f"~/.reverse-api/runs/har/{run_id}/network.har"
+else:
+ # No argument provided
+ Error: "Please provide either a run_id or path to HAR file"
+```
+
+### Step 2: Verify HAR File Exists
+
+Check if the HAR file exists and is readable:
+
+```bash
+if [ -f {har_path} ]; then
+ echo "HAR file found: {har_path}"
+ ls -lh {har_path}
+else
+ echo "Error: HAR file not found at {har_path}"
+ exit 1
+fi
+```
+
+If using run_id but HAR file doesn't exist:
+```
+Error: "No HAR file found for run_id: {run_id}
+
+Expected location: ~/.reverse-api/runs/har/{run_id}/network.har
+
+Available runs:
+{list runs in ~/.reverse-api/runs/}"
+```
+
+### Step 3: List Available Runs (if needed)
+
+If the HAR file is not found and a run_id was provided, list available runs to help the user:
+
+```bash
+ls -1 ~/.reverse-api/runs/ | head -10
+```
+
+Display:
+```
+Available run IDs:
+- abc-123-def (2025-01-01)
+- xyz-789-ghi (2025-01-02)
+...
+
+Use: /reverse-api-engineer:engineer <run_id>
+Or provide direct path: /reverse-api-engineer:engineer /path/to/capture.har
+```
+
+### Step 4: Read Existing Run Metadata (if available)
+
+If using run_id, try to read metadata from history:
+
+```bash
+if [ -f ~/.reverse-api/history.json ]; then
+ # Read history.json and find entry for this run_id
+ # Extract: task, url, timestamp, original mode
+fi
+```
+
+Display context:
+```
+Re-engineering HAR capture:
+- Run ID: {run_id}
+- Original task: {task}
+- Captured on: {timestamp}
+- Original mode: {mode}
+```
+
+### Step 5: Prompt for New Task Description
+
+Ask the user what to focus on for this regeneration:
+
+```
+The HAR file contains captured API traffic from a previous session.
+
+What would you like to generate? (e.g., "focus on authentication endpoints", "create a simpler client", "add pagination support")
+
+Press Enter to use original task: "{original_task}"
+```
+
+If user provides new description, use it. Otherwise, use original task.
+
+### Step 6: Analyze HAR File
+
+Read and parse the HAR file:
+
+```python
+import json
+with open(har_path, "r") as f:
+ har_data = json.load(f)
+```
+
+Use the `reverse-engineering-api` skill guidance to:
+
+1. **Filter relevant entries**: Exclude static assets, analytics, ads, CDN resources
+2. **Identify API endpoints**: Look for `/api/`, `/v1/`, `/graphql`, XHR/Fetch requests
+3. **Extract patterns**:
+ - URL patterns and query parameters
+ - HTTP methods (GET, POST, PUT, DELETE)
+ - Request/response headers
+ - Authentication mechanisms
+ - Request body schemas
+ - Response structures
+
+Summarize findings:
+```
+Analyzing HAR file: {har_path}
+Total entries: {total_count}
+
+Found {count} relevant API endpoints:
+- {method} {endpoint} ({description})
+- {method} {endpoint} ({description})
+...
+
+Authentication detected: {auth_type} (Bearer token / API key / None)
+Base URL: {base_url}
+```
+
+### Step 7: Generate New Run ID
+
+Generate a new run ID for this regeneration:
+
+```python
+import uuid
+new_run_id = str(uuid.uuid4())
+```
+
+This keeps the original capture separate from the new generation.
+
+### Step 8: Generate API Client
+
+Generate a descriptive name for the script based on the task:
+
+```
+task_name = sanitize(task) # e.g., "apple_jobs_api"
+output_dir = ./scripts/{task_name}/
+```
+
+Create output directory:
+```bash
+mkdir -p ./scripts/{task_name}/
+```
+
+Generate `api_client.py` with the following structure:
+
+```python
+"""
+Auto-generated API client for {domain}
+Generated from HAR capture on {date}
+
+Original Run ID: {original_run_id}
+Original HAR file: {har_path}
+Regenerated Run ID: {new_run_id}
+"""
+
+import requests
+from typing import Optional, Dict, Any, List
+import logging
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+
+class {ClassName}Client:
+ """API client for {domain}."""
+
+ def __init__(
+ self,
+ base_url: str = "{base_url}",
+ session: Optional[requests.Session] = None,
+ ):
+ self.base_url = base_url.rstrip("/")
+ self.session = session or requests.Session()
+ self._setup_session()
+
+ def _setup_session(self):
+ """Configure session with default headers."""
+ self.session.headers.update({
+ "User-Agent": "Mozilla/5.0 (compatible)",
+ "Accept": "application/json",
+ # Add detected required headers
+ })
+
+ def _request(
+ self,
+ method: str,
+ endpoint: str,
+ **kwargs,
+ ) -> requests.Response:
+ """Make an HTTP request with error handling."""
+ url = f"{self.base_url}{endpoint}"
+ try:
+ response = self.session.request(method, url, **kwargs)
+ response.raise_for_status()
+ return response
+ except requests.exceptions.RequestException as e:
+ logger.error(f"Request failed: {e}")
+ raise
+
+ # Generated endpoint methods
+ # For each detected endpoint, create a method like:
+
+ def get_example(self, param: str) -> Dict[str, Any]:
+ """
+ {Method description based on endpoint}.
+
+ Args:
+ param: {Parameter description}
+
+ Returns:
+ JSON response data
+
+ Raises:
+ requests.exceptions.RequestException: If request fails
+ """
+ response = self._request("GET", f"/api/example/{param}")
+ return response.json()
+
+
+# Example usage
+if __name__ == "__main__":
+ client = {ClassName}Client()
+ # Add example calls based on captured endpoints
+```
+
+Generate `README.md`:
+```markdown
+# {Task Name} API Client
+
+Auto-generated Python API client from browser traffic capture.
+
+## Generated From
+
+- **Original Run ID**: {original_run_id}
+- **HAR File**: {har_path}
+- **Regenerated**: {date}
+- **Regeneration Run ID**: {new_run_id}
+- **Base URL**: {base_url}
+
+## Installation
+
+```bash
+pip install requests
+```
+
+## Usage
+
+```python
+from api_client import {ClassName}Client
+
+client = {ClassName}Client()
+
+# Example: {endpoint_1}
+result = client.{method_1}({params})
+print(result)
+```
+
+## Available Methods
+
+{List all generated methods with descriptions}
+
+## Authentication
+
+{Describe detected authentication mechanism and how to configure}
+
+## Notes
+
+- Regenerated from previous HAR capture
+- Original capture: {original_date}
+- Endpoints based on observed API calls
+- May require authentication tokens/API keys
+- Test thoroughly before production use
+```
+
+### Step 9: Save Run History
+
+Update `~/.reverse-api/history.json` with run metadata:
+
+```json
+{
+ "run_id": "{new_run_id}",
+ "mode": "engineer",
+ "task": "{task}",
+ "source_run_id": "{original_run_id}",
+ "har_path": "{har_path}",
+ "timestamp": "{ISO timestamp}",
+ "output_dir": "./scripts/{task_name}/",
+ "status": "completed"
+}
+```
+
+### Step 10: Summary
+
+Present final summary to user:
+
+```
+API client re-generated successfully!
+
+Original HAR: {har_path}
+Original Run ID: {original_run_id}
+New Run ID: {new_run_id}
+
+Generated files:
+- ./scripts/{task_name}/api_client.py
+- ./scripts/{task_name}/README.md
+
+Detected endpoints: {count}
+Authentication: {auth_type}
+
+Next steps:
+1. Review the generated code
+2. Test with: python ./scripts/{task_name}/api_client.py
+3. Compare with previous version (if any)
+4. Integrate into your project
+
+To regenerate with different focus:
+/reverse-api-engineer:engineer {original_run_id}
+```
+
+## Error Handling
+
+- **HAR file not found**: Provide list of available runs and suggest correct usage
+- **Invalid HAR format**: Check file is valid JSON and follows HAR specification
+- **No API endpoints found**: All entries were filtered out (suggest adjusting filters or recapturing)
+- **Generation fails**: Retry with different approach or analyze HAR manually
+
+## Tips for Users
+
+- **Different approaches**: Try regenerating with different focus areas
+- **Refinement**: Use engineer mode to improve previous generations
+- **Testing**: Compare multiple generated versions to find the best implementation
+- **Documentation**: Each regeneration creates a new run_id for tracking
+- **Original HAR**: The original HAR file is never modified
+
+## Examples
+
+```
+# Using run_id
+/reverse-api-engineer:engineer abc-123-def
+
+# Using direct path
+/reverse-api-engineer:engineer ~/.reverse-api/runs/xyz-789/har/network.har
+
+# Using relative path
+/reverse-api-engineer:engineer ./captures/myapp.har
+
+# Re-engineer with focus
+/reverse-api-engineer:engineer abc-123-def
+> "focus on authentication endpoints only"
+```
+
+## Use Cases
+
+1. **Improve previous generation**: Regenerate with better endpoint detection
+2. **Extract subset**: Focus on specific endpoints from large capture
+3. **Different implementation**: Generate alternative client architecture
+4. **Update documentation**: Regenerate with better docstrings and examples
+5. **Fix issues**: Address problems in previous generation without re-capturing
diff --git a/plugins/reverse-api-engineer/commands/manual.md b/plugins/reverse-api-engineer/commands/manual.md
new file mode 100644
index 0000000..30eccea
--- /dev/null
+++ b/plugins/reverse-api-engineer/commands/manual.md
@@ -0,0 +1,324 @@
+---
+description: Launch browser with HAR recording, capture traffic manually, then generate Python API client
+argument-hint: "[task] [url]"
+allowed-tools: ["MCP:rae-playwright-mcp", "Read", "Write", "Bash"]
+---
+
+# Manual Mode - Browser Capture and API Generation
+
+Launch a browser with HAR recording enabled. The user will navigate manually to trigger the desired API calls. When the browser closes, analyze the captured HAR file and generate a production-ready Python API client.
+
+## Prerequisites
+
+Ensure the `reverse-engineering-api` skill is loaded for guidance on HAR analysis and code generation.
+
+## Command Arguments
+
+- `task` (optional): Description of what to reverse engineer (e.g., "fetch Apple jobs", "scrape product data")
+- `url` (optional): Starting URL for the browser
+
+If arguments are not provided, prompt the user interactively.
+
+## Workflow
+
+### Step 1: Gather Task Information
+
+If `task` argument is not provided:
+```
+Ask: "What would you like to reverse engineer? (e.g., 'fetch job listings from Company X')"
+```
+
+If `url` argument is not provided:
+```
+Ask: "What URL should I open? (optional, press Enter to skip)"
+```
+
+### Step 2: Generate Run ID and Setup Paths
+
+Generate a unique run ID using UUID format:
+```
+run_id = uuid4() (e.g., "abc-123-def-456")
+```
+
+Setup paths:
+```
+har_dir = ~/.reverse-api/runs/har/{run_id}/
+har_path = {har_dir}/network.har
+```
+
+Ensure directory exists:
+```bash
+mkdir -p ~/.reverse-api/runs/har/{run_id}/
+```
+
+### Step 3: Launch Browser with HAR Recording
+
+Use the Playwright MCP `rae-playwright-mcp` to launch a browser with HAR recording:
+
+```
+Call MCP tool: playwright_navigate
+Parameters:
+ - url: {url} or "about:blank" if no URL provided
+ - options:
+ - record_har: true
+ - har_path: ~/.reverse-api/runs/har/{run_id}/network.har
+```
+
+Inform the user:
+```
+Browser launched with HAR recording enabled.
+Navigate to the website and interact with it to trigger API calls.
+Close the browser when you're done to proceed with analysis.
+
+HAR will be saved to: ~/.reverse-api/runs/har/{run_id}/network.har
+```
+
+### Step 4: Wait for Browser to Close
+
+Monitor the browser session. When it closes, the HAR file will be saved automatically.
+
+Verify HAR file exists:
+```bash
+ls -lh ~/.reverse-api/runs/har/{run_id}/network.har
+```
+
+If file doesn't exist or is empty:
+```
+Error: "HAR file not found or empty. Please ensure you interacted with the website before closing the browser."
+Exit with error
+```
+
+### Step 5: Analyze HAR File
+
+Read and parse the HAR file:
+```python
+import json
+with open("~/.reverse-api/runs/har/{run_id}/network.har", "r") as f:
+ har_data = json.load(f)
+```
+
+Use the `reverse-engineering-api` skill guidance to:
+
+1. **Filter relevant entries**: Exclude static assets, analytics, ads, CDN resources
+2. **Identify API endpoints**: Look for `/api/`, `/v1/`, `/graphql`, XHR/Fetch requests
+3. **Extract patterns**:
+ - URL patterns and query parameters
+ - HTTP methods (GET, POST, PUT, DELETE)
+ - Request/response headers
+ - Authentication mechanisms
+ - Request body schemas
+ - Response structures
+
+Summarize findings:
+```
+Found {count} relevant API endpoints:
+- {method} {endpoint} ({description})
+- {method} {endpoint} ({description})
+...
+
+Authentication detected: {auth_type} (Bearer token / API key / None)
+Base URL: {base_url}
+```
+
+### Step 6: Generate API Client
+
+Generate a descriptive name for the script based on the task:
+```
+task_name = sanitize(task) # e.g., "apple_jobs_api"
+output_dir = ./scripts/{task_name}/
+```
+
+Create output directory:
+```bash
+mkdir -p ./scripts/{task_name}/
+```
+
+Generate `api_client.py` with the following structure:
+
+```python
+"""
+Auto-generated API client for {domain}
+Generated from HAR capture on {date}
+
+Run ID: {run_id}
+HAR file: ~/.reverse-api/runs/har/{run_id}/network.har
+"""
+
+import requests
+from typing import Optional, Dict, Any, List
+import logging
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+
+class {ClassName}Client:
+ """API client for {domain}."""
+
+ def __init__(
+ self,
+ base_url: str = "{base_url}",
+ session: Optional[requests.Session] = None,
+ ):
+ self.base_url = base_url.rstrip("/")
+ self.session = session or requests.Session()
+ self._setup_session()
+
+ def _setup_session(self):
+ """Configure session with default headers."""
+ self.session.headers.update({
+ "User-Agent": "Mozilla/5.0 (compatible)",
+ "Accept": "application/json",
+ # Add detected required headers
+ })
+
+ def _request(
+ self,
+ method: str,
+ endpoint: str,
+ **kwargs,
+ ) -> requests.Response:
+ """Make an HTTP request with error handling."""
+ url = f"{self.base_url}{endpoint}"
+ try:
+ response = self.session.request(method, url, **kwargs)
+ response.raise_for_status()
+ return response
+ except requests.exceptions.RequestException as e:
+ logger.error(f"Request failed: {e}")
+ raise
+
+ # Generated endpoint methods
+ # For each detected endpoint, create a method like:
+
+ def get_example(self, param: str) -> Dict[str, Any]:
+ """
+ {Method description based on endpoint}.
+
+ Args:
+ param: {Parameter description}
+
+ Returns:
+ JSON response data
+
+ Raises:
+ requests.exceptions.RequestException: If request fails
+ """
+ response = self._request("GET", f"/api/example/{param}")
+ return response.json()
+
+
+# Example usage
+if __name__ == "__main__":
+ client = {ClassName}Client()
+ # Add example calls based on captured endpoints
+```
+
+Generate `README.md`:
+```markdown
+# {Task Name} API Client
+
+Auto-generated Python API client from browser traffic capture.
+
+## Generated From
+
+- **Run ID**: {run_id}
+- **HAR File**: ~/.reverse-api/runs/har/{run_id}/network.har
+- **Date**: {date}
+- **Base URL**: {base_url}
+
+## Installation
+
+```bash
+pip install requests
+```
+
+## Usage
+
+```python
+from api_client import {ClassName}Client
+
+client = {ClassName}Client()
+
+# Example: {endpoint_1}
+result = client.{method_1}({params})
+print(result)
+```
+
+## Available Methods
+
+{List all generated methods with descriptions}
+
+## Authentication
+
+{Describe detected authentication mechanism and how to configure}
+
+## Notes
+
+- Generated from captured browser traffic
+- Endpoints based on observed API calls
+- May require authentication tokens/API keys
+- Test thoroughly before production use
+```
+
+### Step 7: Save Run History
+
+Update `~/.reverse-api/history.json` with run metadata:
+
+```json
+{
+ "run_id": "{run_id}",
+ "mode": "manual",
+ "task": "{task}",
+ "url": "{url}",
+ "timestamp": "{ISO timestamp}",
+ "har_path": "~/.reverse-api/runs/har/{run_id}/network.har",
+ "output_dir": "./scripts/{task_name}/",
+ "status": "completed"
+}
+```
+
+### Step 8: Summary
+
+Present final summary to user:
+```
+API client generated successfully!
+
+Run ID: {run_id}
+HAR file: ~/.reverse-api/runs/har/{run_id}/network.har
+
+Generated files:
+- ./scripts/{task_name}/api_client.py
+- ./scripts/{task_name}/README.md
+
+Detected endpoints: {count}
+Authentication: {auth_type}
+
+Next steps:
+1. Review the generated code
+2. Test with: python ./scripts/{task_name}/api_client.py
+3. Integrate into your project
+```
+
+## Error Handling
+
+- **Browser launch fails**: Check Playwright MCP is running and accessible
+- **HAR file empty**: User didn't interact with website, or no network traffic captured
+- **No API endpoints found**: All entries were filtered out (adjust filters or capture more traffic)
+- **Generation fails**: Use `/reverse-api-engineer:engineer {run_id}` to retry with different approach
+
+## Tips for Users
+
+- **Login flows**: Log in during capture to record authentication
+- **Pagination**: Navigate through pages to capture query parameter patterns
+- **Different actions**: Create, read, update, delete to capture all CRUD endpoints
+- **Multiple captures**: You can run manual mode multiple times for different flows
+- **Re-engineer**: Use `/reverse-api-engineer:engineer {run_id}` to regenerate from same capture
+
+## Examples
+
+```
+/reverse-api-engineer:manual "fetch Apple jobs" https://jobs.apple.com
+/reverse-api-engineer:manual "scrape product data"
+/reverse-api-engineer:manual
+```
diff --git a/plugins/reverse-api-engineer/skills/reverse-engineering-api/CHANGELOG.md b/plugins/reverse-api-engineer/skills/reverse-engineering-api/CHANGELOG.md
new file mode 100644
index 0000000..dabebd6
--- /dev/null
+++ b/plugins/reverse-api-engineer/skills/reverse-engineering-api/CHANGELOG.md
@@ -0,0 +1,33 @@
+# Changelog
+
+All notable changes to the Reverse Engineering API skill will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2025-12-31
+
+### Added
+
+- Initial release of the Reverse Engineering API skill
+- Core SKILL.md with 4-phase workflow:
+ - Phase 1: Browser Capture with HAR Recording
+ - Phase 2: HAR Analysis
+ - Phase 3: API Client Generation
+ - Phase 4: Testing & Refinement
+- Reference documentation:
+ - `references/AUTH_PATTERNS.md` - 8 authentication patterns with code examples
+ - `references/HAR_ANALYSIS.md` - HAR parsing and endpoint extraction guide
+- Playwright MCP integration for browser control
+- Support for HAR files at `~/.reverse-api/runs/har/{run_id}/`
+- Decision tree for workflow routing
+- Python API client generation templates
+- Iteration protocol with up to 5 retry attempts
+- Bot detection handling with Playwright fallback
+
+### Dependencies
+
+Scripts require:
+- `aiohttp` - Async HTTP client (required for all scripts)
+- `playwright` - Browser automation (required for mapper.py)
+- `beautifulsoup4` - HTML parsing (optional for crawler.py, falls back to regex)
diff --git a/plugins/reverse-api-engineer/skills/reverse-engineering-api/LICENSE b/plugins/reverse-api-engineer/skills/reverse-engineering-api/LICENSE
new file mode 100644
index 0000000..0b4233a
--- /dev/null
+++ b/plugins/reverse-api-engineer/skills/reverse-engineering-api/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 kalil0321
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/plugins/reverse-api-engineer/skills/reverse-engineering-api/SKILL.md b/plugins/reverse-api-engineer/skills/reverse-engineering-api/SKILL.md
new file mode 100644
index 0000000..0bd4734
--- /dev/null
+++ b/plugins/reverse-api-engineer/skills/reverse-engineering-api/SKILL.md
@@ -0,0 +1,301 @@
+---
+name: reverse-engineering-api
+description: Reverse engineer web APIs by capturing browser traffic (HAR files) and generating production-ready Python API clients. Use when the user wants to create an API client for a website, automate web interactions, or understand undocumented APIs. Activate on tasks mentioning "reverse engineer", "API client", "HAR file", "capture traffic", or "automate website".
+compatibility: Requires Playwright MCP for browser control. HAR files saved to ~/.reverse-api/runs/har/{run_id}
+metadata:
+ author: reverse-api-engineer
+ version: "1.0"
+allowed-tools: Bash(python:*) Bash(uv:*) Read Write Edit
+---
+
+# Reverse Engineering API Skill
+
+This skill enables you to reverse engineer web APIs by:
+1. Controlling a browser with HAR recording enabled
+2. Analyzing captured network traffic
+3. Generating production-ready Python API clients
+
+## Prerequisites
+
+- **Playwright MCP**: You must have access to Playwright MCP tools for browser control
+- **HAR Recording**: The browser must be configured to record HAR files
+- **Python**: For running analysis scripts and generated clients
+
+## Workflow Overview
+
+```
+[User Task] -> [Browser Capture] -> [HAR Analysis] -> [API Client Generation] -> [Testing & Refinement]
+```
+
+## Phase 1: Browser Capture with HAR Recording
+
+### Starting the Browser
+
+When starting a browser session for API capture:
+
+1. Launch browser with HAR recording enabled via Playwright MCP
+2. Generate a unique run ID: `{uuid}`
+3. Configure HAR output path: `~/.reverse-api/runs/har/{id}/network.har`
+
+### During Capture
+
+Navigate autonomously to trigger the API calls needed:
+- Login flows (capture authentication)
+- Data fetching (capture GET endpoints)
+- Form submissions (capture POST/PUT endpoints)
+- Pagination (capture query parameter patterns)
+
+### On Browser Close
+
+When the browser closes, note the HAR file location:
+```
+HAR file saved to: ~/.reverse-api/runs/har/{run_id}/network.har
+```
+
+## Phase 2: HAR Analysis
+
+### Reading the HAR File
+
+HAR files are JSON with this structure:
+```json
+{
+ "log": {
+ "entries": [
+ {
+ "request": {
+ "method": "GET|POST|PUT|DELETE",
+ "url": "https://api.example.com/endpoint",
+ "headers": [...],
+ "postData": {...}
+ },
+ "response": {
+ "status": 200,
+ "headers": [...],
+ "content": {...}
+ }
+ }
+ ]
+ }
+}
+```
+
+### Filtering Relevant Entries
+
+Filter out noise by excluding:
+- Static assets: `.js`, `.css`, `.png`, `.jpg`, `.svg`, `.woff`, `.ico`
+- Analytics: `google-analytics`, `segment`, `mixpanel`, `hotjar`
+- Ads: `doubleclick`, `adsense`, `facebook.com/tr`
+- CDN resources: `cloudflare`, `cdn.`, `static.`
+
+Focus on:
+- API endpoints: `/api/`, `/v1/`, `/v2/`, `/graphql`
+- XHR/Fetch requests with JSON responses
+- Requests with authentication headers
+
+### Extracting Patterns
+
+For each relevant endpoint, extract:
+
+1. **URL Pattern**: Base URL, path, query parameters
+2. **Method**: GET, POST, PUT, DELETE, PATCH
+3. **Headers**:
+ - Required headers (Authorization, Content-Type, custom headers)
+ - Optional headers (User-Agent, Accept)
+4. **Request Body**: JSON schema, form data structure
+5. **Response Schema**: JSON structure, status codes
+6. **Authentication**: See [references/AUTH_PATTERNS.md](references/AUTH_PATTERNS.md)
+
+## Phase 3: API Client Generation
+
+### Code Structure
+
+Generate a Python module with:
+
+```
+{output_dir}/
+ api_client.py # Main API client class
+ README.md # Usage documentation
+```
+
+### api_client.py Template
+
+```python
+"""
+Auto-generated API client for {domain}
+Generated from HAR capture on {date}
+"""
+
+import requests
+from typing import Optional, Dict, Any, List
+import logging
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+
+class {ClassName}Client:
+ """API client for {domain}."""
+
+ def __init__(
+ self,
+ base_url: str = "{base_url}",
+ session: Optional[requests.Session] = None,
+ ):
+ self.base_url = base_url.rstrip("/")
+ self.session = session or requests.Session()
+ self._setup_session()
+
+ def _setup_session(self):
+ """Configure session with default headers."""
+ self.session.headers.update({
+ "User-Agent": "Mozilla/5.0 (compatible)",
+ "Accept": "application/json",
+ # Add other required headers
+ })
+
+ def _request(
+ self,
+ method: str,
+ endpoint: str,
+ **kwargs,
+ ) -> requests.Response:
+ """Make an HTTP request with error handling."""
+ url = f"{self.base_url}{endpoint}"
+ try:
+ response = self.session.request(method, url, **kwargs)
+ response.raise_for_status()
+ return response
+ except requests.exceptions.RequestException as e:
+ logger.error(f"Request failed: {e}")
+ raise
+
+ # Generated endpoint methods go here
+ def get_example(self, param: str) -> Dict[str, Any]:
+ """
+ Fetch example data.
+
+ Args:
+ param: Description of parameter
+
+ Returns:
+ JSON response data
+ """
+ response = self._request("GET", f"/api/example/{param}")
+ return response.json()
+
+
+# Example usage
+if __name__ == "__main__":
+ client = {ClassName}Client()
+ # Example calls
+```
+
+### Code Quality Requirements
+
+All generated code must include:
+
+1. **Type hints** for all parameters and return values
+2. **Docstrings** for all public methods
+3. **Error handling** with try-except blocks
+4. **Logging** for debugging
+5. **Session management** for connection reuse
+6. **Authentication handling** based on detected patterns
+
+## Phase 4: Testing & Refinement
+
+### Testing the Generated Client
+
+After generating the client:
+
+1. Run the example usage section
+2. Verify responses match expected structure
+3. Handle any errors encountered
+
+### Iteration Protocol
+
+You have up to 5 attempts to fix issues:
+
+```
+Attempt 1: Initial implementation
+ - What was tried
+ - What failed (if anything)
+ - What was changed
+
+Attempt 2: Refinement
+ ...
+```
+
+### Common Issues
+
+| Issue | Solution |
+|-------|----------|
+| 403 Forbidden | Add missing headers, check authentication |
+| Bot detection | Switch to Playwright with stealth mode |
+| Rate limiting | Add delays, respect Retry-After headers |
+| Session expiry | Implement token refresh logic |
+| CORS errors | Use server-side requests (not applicable to Python) |
+
+## Domain Discovery (Optional)
+
+Before capture, you may want to map the domain to understand its structure.
+
+### Using the Mapper Script
+
+Run `scripts/mapper.py` to quickly discover:
+- All pages on the domain or subdomains
+- Subdomains
+
+It is useful for generalizing your scripts on multitenants websites.
+
+For example, for Ashby ATS or Workday it's useful to find other companies using this ATS when trying to generalize your script.
+
+```bash
+python scripts/mapper.py https://example.com
+```
+
+### Using the Sitemap Parser
+
+Run `scripts/sitemap.py` to extract URLs from sitemaps:
+
+```bash
+python scripts/sitemap.py https://example.com
+```
+
+## Output Locations
+
+- **HAR files**: `~/.reverse-api/runs/har/{run_id}/`
+- **Generated scripts**: `./{task_name}`
+
+## Example Session
+
+```
+User: "Create an API client for the Apple Jobs website"
+
+
+1. [Browser Capture]
+ Launch browser with HAR recording
+ Navigate to jobs.apple.com
+ Perform search, browse listings
+ Close browser
+ HAR saved to: ~/.reverse-api/runs/har/{id}/network.har
+
+ Note: you can monitor browser requests with the Playwright MCP
+
+2. [HAR Analysis]
+ Found endpoints:
+ - GET /api/role/search?query=...
+ - GET /api/role/{id}
+ Authentication: None required (public API)
+
+3. [Generate Client]
+ Create : {task_name}/api_client.py
+
+4. [Test]
+ Ran example usage - Success!
+
+5. [Summary]
+ Generated Apple Jobs API client with:
+ - search_roles(query, location, page)
+ - get_role(role_id)
+ Files: ./{task_name}/
+```
diff --git a/plugins/reverse-api-engineer/skills/reverse-engineering-api/references/AUTH_PATTERNS.md b/plugins/reverse-api-engineer/skills/reverse-engineering-api/references/AUTH_PATTERNS.md
new file mode 100644
index 0000000..7554b4f
--- /dev/null
+++ b/plugins/reverse-api-engineer/skills/reverse-engineering-api/references/AUTH_PATTERNS.md
@@ -0,0 +1,575 @@
+# Authentication Patterns Reference
+
+This document covers common authentication patterns found in web APIs and how to handle them when generating API clients. These patterns align with the reverse-api-engineer codebase conventions.
+
+## Overview
+
+When analyzing HAR files, identify authentication by checking:
+- Request headers: `Authorization`, `X-API-Key`, `X-Token`, `Cookie`
+- Response headers: `Set-Cookie`, `X-CSRF-Token`
+- Request body: `username`, `password`, `token`, `api_key`
+- Response body: `access_token`, `refresh_token`, `session_id`
+- Query parameters: `key`, `api_key`, `token`, `access_token`
+- Login endpoints: `/login`, `/auth`, `/oauth/token`, `/api/auth`
+
+---
+
+## 1. Bearer Token (JWT)
+
+### Detection in HAR
+```json
+{
+ "name": "Authorization",
+ "value": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
+}
+```
+
+### Generated Client Pattern
+```python
+"""
+API client with Bearer token authentication.
+Generated by reverse-api-engineer.
+"""
+
+import requests
+from typing import Optional, Dict, Any
+import logging
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+
+class APIClient:
+ """API client with Bearer token authentication."""
+
+ def __init__(
+ self,
+ base_url: str,
+ token: str,
+ session: Optional[requests.Session] = None,
+ ):
+ self.base_url = base_url.rstrip("/")
+ self.token = token
+ self.session = session or requests.Session()
+ self._setup_session()
+
+ def _setup_session(self):
+ """Configure session with authentication headers."""
+ self.session.headers.update({
+ "Authorization": f"Bearer {self.token}",
+ "Accept": "application/json",
+ "Content-Type": "application/json",
+ })
+
+ def _request(
+ self,
+ method: str,
+ endpoint: str,
+ **kwargs,
+ ) -> requests.Response:
+ """Make an HTTP request with error handling."""
+ url = f"{self.base_url}{endpoint}"
+ try:
+ response = self.session.request(method, url, **kwargs)
+ response.raise_for_status()
+ return response
+ except requests.exceptions.RequestException as e:
+ logger.error(f"Request failed: {e}")
+ raise
+```
+
+### Token Refresh Pattern
+If you detect a `/refresh` or `/token/refresh` endpoint in the HAR:
+```python
+def refresh_token(self, refresh_token: str) -> str:
+ """
+ Refresh the access token.
+
+ Args:
+ refresh_token: The refresh token from initial auth
+
+ Returns:
+ New access token
+ """
+ response = self._request("POST", "/auth/refresh", json={
+ "refresh_token": refresh_token
+ })
+ data = response.json()
+ self.token = data["access_token"]
+ self.session.headers["Authorization"] = f"Bearer {self.token}"
+ return self.token
+```
+
+---
+
+## 2. API Key
+
+### Detection in HAR
+Header-based:
+```json
+{"name": "X-API-Key", "value": "sk_live_xxxxx"}
+```
+
+Query parameter:
+```json
+{"name": "api_key", "value": "xxxxx"}
+```
+
+### Generated Client Pattern (Header)
+```python
+class APIClient:
+ """API client with API key authentication."""
+
+ def __init__(
+ self,
+ base_url: str,
+ api_key: str,
+ session: Optional[requests.Session] = None,
+ ):
+ self.base_url = base_url.rstrip("/")
+ self.api_key = api_key
+ self.session = session or requests.Session()
+ self._setup_session()
+
+ def _setup_session(self):
+ """Configure session with API key header."""
+ self.session.headers.update({
+ "X-API-Key": self.api_key,
+ "Accept": "application/json",
+ })
+```
+
+### Generated Client Pattern (Query Parameter)
+```python
+class APIClient:
+ """API client with API key in query parameters."""
+
+ def __init__(self, base_url: str, api_key: str):
+ self.base_url = base_url.rstrip("/")
+ self.api_key = api_key
+ self.session = requests.Session()
+
+ def _request(
+ self,
+ method: str,
+ endpoint: str,
+ **kwargs,
+ ) -> requests.Response:
+ """Make request with API key in query params."""
+ url = f"{self.base_url}{endpoint}"
+ params = kwargs.pop("params", {})
+ params["api_key"] = self.api_key
+ try:
+ response = self.session.request(method, url, params=params, **kwargs)
+ response.raise_for_status()
+ return response
+ except requests.exceptions.RequestException as e:
+ logger.error(f"Request failed: {e}")
+ raise
+```
+
+---
+
+## 3. Session Cookies
+
+### Detection in HAR
+Look for `Set-Cookie` in response headers after login:
+```json
+{"name": "Set-Cookie", "value": "sessionid=abc123; Path=/; HttpOnly"}
+```
+
+Common cookie names: `sessionid`, `PHPSESSID`, `connect.sid`, `_session`
+
+### Generated Client Pattern
+```python
+class APIClient:
+ """API client with session-based authentication."""
+
+ def __init__(self, base_url: str):
+ self.base_url = base_url.rstrip("/")
+ self.session = requests.Session() # Automatically handles cookies
+
+ def login(self, username: str, password: str) -> bool:
+ """
+ Authenticate with username and password.
+
+ Args:
+ username: User's username
+ password: User's password
+
+ Returns:
+ True if login successful
+ """
+ try:
+ response = self.session.post(
+ f"{self.base_url}/login",
+ data={"username": username, "password": password}
+ )
+ response.raise_for_status()
+ return True
+ except requests.exceptions.RequestException as e:
+ logger.error(f"Login failed: {e}")
+ return False
+
+ def _request(
+ self,
+ method: str,
+ endpoint: str,
+ **kwargs,
+ ) -> requests.Response:
+ """Make request with session cookies."""
+ url = f"{self.base_url}{endpoint}"
+ try:
+ response = self.session.request(method, url, **kwargs)
+ response.raise_for_status()
+ return response
+ except requests.exceptions.RequestException as e:
+ logger.error(f"Request failed: {e}")
+ raise
+```
+
+---
+
+## 4. CSRF Tokens
+
+### Detection in HAR
+Hidden form field in HTML:
+```html
+<input type="hidden" name="csrf_token" value="...">
+```
+
+Header in requests:
+```json
+{"name": "X-CSRF-Token", "value": "..."}
+```
+
+Cookie:
+```json
+{"name": "csrftoken", "value": "..."}
+```
+
+### Generated Client Pattern
+```python
+import re
+
+
+class APIClient:
+ """API client with CSRF token handling."""
+
+ def __init__(self, base_url: str):
+ self.base_url = base_url.rstrip("/")
+ self.session = requests.Session()
+ self.csrf_token: Optional[str] = None
+
+ def _get_csrf_token(self) -> str:
+ """Fetch CSRF token from cookie or page."""
+ # Option 1: From cookie
+ if "csrftoken" in self.session.cookies:
+ return self.session.cookies["csrftoken"]
+
+ # Option 2: From page content
+ response = self.session.get(f"{self.base_url}/")
+ match = re.search(r'csrf_token["\']:\s*["\']([^"\']+)', response.text)
+ if match:
+ return match.group(1)
+
+ # Option 3: From meta tag
+ match = re.search(r'<meta name="csrf-token" content="([^"]+)"', response.text)
+ if match:
+ return match.group(1)
+
+ return ""
+
+ def _request(
+ self,
+ method: str,
+ endpoint: str,
+ **kwargs,
+ ) -> requests.Response:
+ """Make request with CSRF token for mutating operations."""
+ url = f"{self.base_url}{endpoint}"
+
+ # Add CSRF token for POST, PUT, DELETE, PATCH
+ if method.upper() in ("POST", "PUT", "DELETE", "PATCH"):
+ if not self.csrf_token:
+ self.csrf_token = self._get_csrf_token()
+ headers = kwargs.pop("headers", {})
+ headers["X-CSRF-Token"] = self.csrf_token
+ kwargs["headers"] = headers
+
+ try:
+ response = self.session.request(method, url, **kwargs)
+ response.raise_for_status()
+ return response
+ except requests.exceptions.RequestException as e:
+ logger.error(f"Request failed: {e}")
+ raise
+```
+
+---
+
+## 5. OAuth 2.0
+
+### Detection in HAR
+Look for:
+- Token endpoint: `/oauth/token`, `/auth/token`
+- `grant_type` in request body
+- `access_token` and `refresh_token` in response
+
+### Generated Client Pattern (Client Credentials)
+```python
+class APIClient:
+ """API client with OAuth 2.0 Client Credentials flow."""
+
+ def __init__(
+ self,
+ base_url: str,
+ client_id: str,
+ client_secret: str,
+ ):
+ self.base_url = base_url.rstrip("/")
+ self.client_id = client_id
+ self.client_secret = client_secret
+ self.access_token: Optional[str] = None
+ self.refresh_token: Optional[str] = None
+ self.session = requests.Session()
+
+ def authenticate(self) -> bool:
+ """
+ Authenticate using Client Credentials flow.
+
+ Returns:
+ True if authentication successful
+ """
+ try:
+ response = requests.post(
+ f"{self.base_url}/oauth/token",
+ data={
+ "grant_type": "client_credentials",
+ "client_id": self.client_id,
+ "client_secret": self.client_secret,
+ }
+ )
+ response.raise_for_status()
+ data = response.json()
+ self.access_token = data["access_token"]
+ self.refresh_token = data.get("refresh_token")
+ self.session.headers["Authorization"] = f"Bearer {self.access_token}"
+ return True
+ except requests.exceptions.RequestException as e:
+ logger.error(f"OAuth authentication failed: {e}")
+ return False
+```
+
+---
+
+## 6. Basic Authentication
+
+### Detection in HAR
+```json
+{"name": "Authorization", "value": "Basic dXNlcm5hbWU6cGFzc3dvcmQ="}
+```
+
+The value is base64 encoded `username:password`.
+
+### Generated Client Pattern
+```python
+from requests.auth import HTTPBasicAuth
+
+
+class APIClient:
+ """API client with HTTP Basic authentication."""
+
+ def __init__(
+ self,
+ base_url: str,
+ username: str,
+ password: str,
+ ):
+ self.base_url = base_url.rstrip("/")
+ self.session = requests.Session()
+ self.session.auth = HTTPBasicAuth(username, password)
+ self.session.headers.update({
+ "Accept": "application/json",
+ })
+```
+
+---
+
+## 7. Custom Headers
+
+### Detection in HAR
+Non-standard headers like:
+```json
+{"name": "X-App-Token", "value": "..."}
+{"name": "X-Client-Id", "value": "..."}
+{"name": "X-Request-Id", "value": "..."}
+```
+
+### Generated Client Pattern
+```python
+class APIClient:
+ """API client with custom header authentication."""
+
+ def __init__(
+ self,
+ base_url: str,
+ app_token: str,
+ client_id: str,
+ ):
+ self.base_url = base_url.rstrip("/")
+ self.session = requests.Session()
+ self._setup_session(app_token, client_id)
+
+ def _setup_session(self, app_token: str, client_id: str):
+ """Configure session with custom headers."""
+ self.session.headers.update({
+ "X-App-Token": app_token,
+ "X-Client-Id": client_id,
+ "Accept": "application/json",
+ })
+```
+
+---
+
+## 8. Signed Requests (HMAC)
+
+### Detection in HAR
+Look for:
+- Signature headers: `X-Signature`, `X-Hmac-Signature`
+- Timestamp headers: `X-Timestamp`, `X-Request-Timestamp`
+- Nonce headers: `X-Nonce`
+
+### Generated Client Pattern
+```python
+import hmac
+import hashlib
+import time
+import uuid
+
+
+class APIClient:
+ """API client with HMAC request signing."""
+
+ def __init__(
+ self,
+ base_url: str,
+ api_key: str,
+ secret: str,
+ ):
+ self.base_url = base_url.rstrip("/")
+ self.api_key = api_key
+ self.secret = secret
+ self.session = requests.Session()
+
+ def _sign_request(
+ self,
+ method: str,
+ path: str,
+ body: str = "",
+ ) -> Dict[str, str]:
+ """
+ Generate signature headers for request.
+
+ Args:
+ method: HTTP method
+ path: Request path
+ body: Request body as string
+
+ Returns:
+ Dictionary of signature headers
+ """
+ timestamp = str(int(time.time()))
+ nonce = str(uuid.uuid4())
+ message = f"{method}{path}{timestamp}{nonce}{body}"
+
+ signature = hmac.new(
+ self.secret.encode(),
+ message.encode(),
+ hashlib.sha256
+ ).hexdigest()
+
+ return {
+ "X-API-Key": self.api_key,
+ "X-Timestamp": timestamp,
+ "X-Nonce": nonce,
+ "X-Signature": signature,
+ }
+
+ def _request(
+ self,
+ method: str,
+ endpoint: str,
+ **kwargs,
+ ) -> requests.Response:
+ """Make signed request."""
+ url = f"{self.base_url}{endpoint}"
+ body = kwargs.get("json", kwargs.get("data", ""))
+ if isinstance(body, dict):
+ import json
+ body = json.dumps(body)
+
+ headers = kwargs.pop("headers", {})
+ headers.update(self._sign_request(method, endpoint, body))
+ kwargs["headers"] = headers
+
+ try:
+ response = self.session.request(method, url, **kwargs)
+ response.raise_for_status()
+ return response
+ except requests.exceptions.RequestException as e:
+ logger.error(f"Request failed: {e}")
+ raise
+```
+
+---
+
+## Priority Order
+
+When multiple auth methods are detected in HAR, use this priority:
+
+1. **OAuth 2.0** - Most robust for production
+2. **Bearer Token** - Simple and stateless
+3. **Session Cookies** - Required for some sites
+4. **API Key** - Simple but less secure
+5. **Basic Auth** - Only if no other option
+
+---
+
+## Bot Detection Fallback
+
+If `requests` fails with 403/captcha, switch to Playwright:
+
+```python
+from playwright.sync_api import sync_playwright
+
+
+class PlaywrightClient:
+ """Playwright-based client for sites with bot detection."""
+
+ def __init__(self, base_url: str):
+ self.base_url = base_url.rstrip("/")
+ self.playwright = None
+ self.browser = None
+ self.context = None
+ self.page = None
+
+ def __enter__(self):
+ self.playwright = sync_playwright().start()
+ self.browser = self.playwright.chromium.launch(headless=True)
+ self.context = self.browser.new_context()
+ self.page = self.context.new_page()
+ return self
+
+ def __exit__(self, exc_type, exc_val, exc_tb):
+ if self.browser:
+ self.browser.close()
+ if self.playwright:
+ self.playwright.stop()
+
+ def get(self, endpoint: str) -> dict:
+ """Make GET request via browser."""
+ url = f"{self.base_url}{endpoint}"
+ response = self.page.goto(url)
+ return self.page.evaluate("() => JSON.parse(document.body.innerText)")
+```
diff --git a/plugins/reverse-api-engineer/skills/reverse-engineering-api/references/HAR_ANALYSIS.md b/plugins/reverse-api-engineer/skills/reverse-engineering-api/references/HAR_ANALYSIS.md
new file mode 100644
index 0000000..2c78e7b
--- /dev/null
+++ b/plugins/reverse-api-engineer/skills/reverse-engineering-api/references/HAR_ANALYSIS.md
@@ -0,0 +1,381 @@
+# HAR File Analysis Reference
+
+This document covers how to analyze HAR (HTTP Archive) files to extract API endpoints and patterns.
+
+## HAR File Structure
+
+```json
+{
+ "log": {
+ "version": "1.2",
+ "creator": { "name": "Browser", "version": "1.0" },
+ "entries": [
+ {
+ "startedDateTime": "2025-01-01T12:00:00.000Z",
+ "time": 150,
+ "request": { ... },
+ "response": { ... },
+ "cache": {},
+ "timings": { ... }
+ }
+ ]
+ }
+}
+```
+
+## Entry Structure
+
+### Request Object
+```json
+{
+ "method": "POST",
+ "url": "https://api.example.com/v1/users",
+ "httpVersion": "HTTP/2.0",
+ "headers": [
+ { "name": "Content-Type", "value": "application/json" },
+ { "name": "Authorization", "value": "Bearer xxx" }
+ ],
+ "queryString": [
+ { "name": "page", "value": "1" }
+ ],
+ "postData": {
+ "mimeType": "application/json",
+ "text": "{\"name\": \"John\"}"
+ },
+ "cookies": [
+ { "name": "session", "value": "abc123" }
+ ]
+}
+```
+
+### Response Object
+```json
+{
+ "status": 200,
+ "statusText": "OK",
+ "headers": [
+ { "name": "Content-Type", "value": "application/json" }
+ ],
+ "content": {
+ "size": 1024,
+ "mimeType": "application/json",
+ "text": "{\"id\": 1, \"name\": \"John\"}"
+ }
+}
+```
+
+## Filtering Entries
+
+### URLs to Exclude
+
+**Static Assets:**
+- `.js`, `.css`, `.map`
+- `.png`, `.jpg`, `.jpeg`, `.gif`, `.svg`, `.webp`, `.ico`
+- `.woff`, `.woff2`, `.ttf`, `.eot`
+- `.mp4`, `.webm`, `.mp3`
+
+**Analytics & Tracking:**
+- `google-analytics.com`
+- `googletagmanager.com`
+- `segment.io`, `segment.com`
+- `mixpanel.com`
+- `hotjar.com`
+- `facebook.com/tr`
+- `doubleclick.net`
+- `adsense`
+
+**CDN Resources:**
+- `cdn.`, `static.`, `assets.`
+- `cloudflare.com`
+- `cloudfront.net`
+- `akamai`
+
+### URLs to Focus On
+
+**API Patterns:**
+- `/api/`
+- `/v1/`, `/v2/`, `/v3/`
+- `/graphql`
+- `/rest/`
+- `/data/`
+
+**Content Types:**
+- `application/json`
+- `application/xml`
+- `text/plain` (sometimes API responses)
+
+## Extracting Endpoints
+
+### Step 1: Parse HAR
+```python
+import json
+from urllib.parse import urlparse, parse_qs
+
+def load_har(path: str) -> dict:
+ with open(path) as f:
+ return json.load(f)
+
+har = load_har("capture.har")
+entries = har["log"]["entries"]
+```
+
+### Step 2: Filter Relevant Entries
+```python
+SKIP_EXTENSIONS = {'.js', '.css', '.png', '.jpg', '.svg', '.woff', '.ico'}
+SKIP_DOMAINS = {'google-analytics.com', 'facebook.com', 'segment.io'}
+
+def is_relevant(entry: dict) -> bool:
+ url = entry["request"]["url"]
+ parsed = urlparse(url)
+
+ # Skip static assets
+ if any(parsed.path.endswith(ext) for ext in SKIP_EXTENSIONS):
+ return False
+
+ # Skip tracking
+ if any(d in parsed.netloc for d in SKIP_DOMAINS):
+ return False
+
+ # Check for API patterns
+ if any(p in parsed.path for p in ['/api/', '/v1/', '/graphql']):
+ return True
+
+ # Check content type
+ response = entry["response"]
+ content_type = next(
+ (h["value"] for h in response["headers"]
+ if h["name"].lower() == "content-type"),
+ ""
+ )
+ if "application/json" in content_type:
+ return True
+
+ return False
+
+api_entries = [e for e in entries if is_relevant(e)]
+```
+
+### Step 3: Group by Endpoint
+```python
+from collections import defaultdict
+
+endpoints = defaultdict(list)
+
+for entry in api_entries:
+ request = entry["request"]
+ url = request["url"]
+ parsed = urlparse(url)
+
+ # Create endpoint key (method + path without query)
+ method = request["method"]
+ path = parsed.path
+ key = f"{method} {path}"
+
+ endpoints[key].append(entry)
+
+# Analyze each endpoint
+for key, entries in endpoints.items():
+ print(f"\n{key}")
+ print(f" Calls: {len(entries)}")
+
+ # Get unique query parameters
+ all_params = set()
+ for e in entries:
+ for param in e["request"].get("queryString", []):
+ all_params.add(param["name"])
+ if all_params:
+ print(f" Query params: {', '.join(all_params)}")
+```
+
+### Step 4: Extract Request Schema
+```python
+def extract_request_schema(entries: list) -> dict:
+ """Infer request body schema from multiple calls."""
+ schemas = []
+
+ for entry in entries:
+ post_data = entry["request"].get("postData", {})
+ if post_data.get("mimeType") == "application/json":
+ try:
+ body = json.loads(post_data.get("text", "{}"))
+ schemas.append(body)
+ except:
+ pass
+
+ if not schemas:
+ return {}
+
+ # Merge schemas to find common fields
+ all_keys = set()
+ for s in schemas:
+ if isinstance(s, dict):
+ all_keys.update(s.keys())
+
+ return {
+ "type": "object",
+ "properties": {k: {"type": "unknown"} for k in all_keys}
+ }
+```
+
+### Step 5: Extract Response Schema
+```python
+def extract_response_schema(entries: list) -> dict:
+ """Infer response schema from multiple calls."""
+ for entry in entries:
+ content = entry["response"].get("content", {})
+ if content.get("mimeType") == "application/json":
+ try:
+ text = content.get("text", "")
+ if text:
+ data = json.loads(text)
+ return infer_schema(data)
+ except:
+ pass
+ return {}
+
+def infer_schema(data) -> dict:
+ """Infer JSON schema from data."""
+ if isinstance(data, dict):
+ return {
+ "type": "object",
+ "properties": {k: infer_schema(v) for k, v in data.items()}
+ }
+ elif isinstance(data, list):
+ if data:
+ return {"type": "array", "items": infer_schema(data[0])}
+ return {"type": "array", "items": {}}
+ elif isinstance(data, bool):
+ return {"type": "boolean"}
+ elif isinstance(data, int):
+ return {"type": "integer"}
+ elif isinstance(data, float):
+ return {"type": "number"}
+ elif isinstance(data, str):
+ return {"type": "string"}
+ else:
+ return {"type": "null"}
+```
+
+## Identifying Path Parameters
+
+Look for patterns in paths:
+```python
+import re
+
+def find_path_params(paths: list[str]) -> str:
+ """Find path parameters by looking at variations."""
+ # Example: ["/users/1", "/users/2", "/users/3"] -> "/users/{id}"
+
+ # Split paths into segments
+ segments_list = [p.strip("/").split("/") for p in paths]
+
+ if not segments_list:
+ return ""
+
+ result = []
+ num_segments = len(segments_list[0])
+
+ for i in range(num_segments):
+ values = set(s[i] for s in segments_list if len(s) > i)
+
+ # If all values are the same, it's a static segment
+ if len(values) == 1:
+ result.append(values.pop())
+ # If values look like IDs (numbers, UUIDs), it's a parameter
+ elif all(v.isdigit() or is_uuid(v) for v in values):
+ result.append("{id}")
+ else:
+ result.append("{param}")
+
+ return "/" + "/".join(result)
+
+def is_uuid(s: str) -> bool:
+ pattern = r'^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
+ return bool(re.match(pattern, s, re.IGNORECASE))
+```
+
+## Extracting Headers
+
+### Required vs Optional Headers
+```python
+def analyze_headers(entries: list) -> tuple[set, set]:
+ """Determine required vs optional headers."""
+ all_headers = []
+
+ for entry in entries:
+ headers = {h["name"].lower(): h["value"]
+ for h in entry["request"]["headers"]}
+ all_headers.append(headers)
+
+ if not all_headers:
+ return set(), set()
+
+ # Headers present in ALL requests are required
+ required = set(all_headers[0].keys())
+ for h in all_headers[1:]:
+ required &= set(h.keys())
+
+ # Headers present in SOME requests are optional
+ all_keys = set()
+ for h in all_headers:
+ all_keys.update(h.keys())
+ optional = all_keys - required
+
+ # Filter out browser-added headers
+ browser_headers = {
+ 'accept', 'accept-encoding', 'accept-language',
+ 'connection', 'host', 'user-agent', 'sec-ch-ua',
+ 'sec-ch-ua-mobile', 'sec-ch-ua-platform', 'sec-fetch-dest',
+ 'sec-fetch-mode', 'sec-fetch-site', 'referer', 'origin'
+ }
+
+ required -= browser_headers
+ optional -= browser_headers
+
+ return required, optional
+```
+
+## Common Patterns
+
+### Pagination
+Look for:
+- Query params: `page`, `offset`, `limit`, `cursor`, `after`, `before`
+- Response fields: `next`, `previous`, `total`, `has_more`, `next_cursor`
+
+### Filtering
+Look for:
+- Query params: `filter`, `q`, `search`, `query`, `sort`, `order`
+
+### GraphQL
+Look for:
+- POST to `/graphql`
+- Body with `query` and `variables` fields
+- Response with `data` and `errors` fields
+
+## Output Format
+
+After analysis, generate a summary:
+
+```markdown
+## API Summary
+
+### Base URL
+https://api.example.com
+
+### Authentication
+Bearer token in Authorization header
+
+### Endpoints
+
+#### GET /api/users
+- Query params: page (int), limit (int)
+- Response: Array of User objects
+
+#### POST /api/users
+- Body: { name: string, email: string }
+- Response: User object
+
+#### GET /api/users/{id}
+- Path params: id (int)
+- Response: User object
+```
diff --git a/plugins/reverse-api-engineer/skills/reverse-engineering-api/templates/api_client.py b/plugins/reverse-api-engineer/skills/reverse-engineering-api/templates/api_client.py
new file mode 100644
index 0000000..220fa63
--- /dev/null
+++ b/plugins/reverse-api-engineer/skills/reverse-engineering-api/templates/api_client.py
@@ -0,0 +1,464 @@
+#!/usr/bin/env python3
+"""
+API Client Template for Reverse Engineered APIs
+
+This template provides a production-ready structure for API clients
+generated from HAR file analysis.
+
+Usage:
+ 1. Copy this template
+ 2. Update BASE_URL, headers, and authentication
+ 3. Add endpoint methods based on HAR analysis
+ 4. Test and refine
+"""
+
+import logging
+import time
+from typing import Any, Dict, List, Optional, Union
+from urllib.parse import urljoin
+
+import requests
+from requests.adapters import HTTPAdapter
+from urllib3.util.retry import Retry
+
+# Configure logging
+logging.basicConfig(
+ level=logging.INFO,
+ format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+)
+logger = logging.getLogger(__name__)
+
+
+class APIError(Exception):
+ """Custom exception for API errors."""
+
+ def __init__(self, message: str, status_code: int = None, response: dict = None):
+ super().__init__(message)
+ self.status_code = status_code
+ self.response = response
+
+
+class RateLimitError(APIError):
+ """Exception for rate limit errors."""
+
+ def __init__(self, message: str, retry_after: int = None):
+ super().__init__(message, status_code=429)
+ self.retry_after = retry_after
+
+
+class APIClient:
+ """
+ Production-ready API client.
+
+ Features:
+ - Automatic retry with exponential backoff
+ - Session management for connection pooling
+ - Configurable authentication
+ - Rate limit handling
+ - Comprehensive logging
+ """
+
+ # Update these based on HAR analysis
+ BASE_URL = "https://api.example.com"
+ DEFAULT_TIMEOUT = 30
+ MAX_RETRIES = 3
+
+ def __init__(
+ self,
+ base_url: str = None,
+ api_key: str = None,
+ access_token: str = None,
+ session_cookie: str = None,
+ timeout: int = None,
+ ):
+ """
+ Initialize the API client.
+
+ Args:
+ base_url: Override the default base URL
+ api_key: API key for X-API-Key authentication
+ access_token: Bearer token for Authorization header
+ session_cookie: Session cookie value
+ timeout: Request timeout in seconds
+ """
+ self.base_url = (base_url or self.BASE_URL).rstrip('/')
+ self.timeout = timeout or self.DEFAULT_TIMEOUT
+
+ # Setup session with retry strategy
+ self.session = requests.Session()
+
+ retry_strategy = Retry(
+ total=self.MAX_RETRIES,
+ backoff_factor=1,
+ status_forcelist=[500, 502, 503, 504],
+ allowed_methods=["GET", "POST", "PUT", "PATCH", "DELETE"],
+ )
+ adapter = HTTPAdapter(max_retries=retry_strategy)
+ self.session.mount("http://", adapter)
+ self.session.mount("https://", adapter)
+
+ # Set default headers (update based on HAR analysis)
+ self.session.headers.update({
+ 'User-Agent': 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36',
+ 'Accept': 'application/json',
+ 'Accept-Language': 'en-US,en;q=0.9',
+ })
+
+ # Configure authentication
+ if api_key:
+ self.session.headers['X-API-Key'] = api_key
+ if access_token:
+ self.session.headers['Authorization'] = f'Bearer {access_token}'
+ if session_cookie:
+ self.session.cookies.set('session', session_cookie)
+
+ def _build_url(self, endpoint: str) -> str:
+ """Build full URL from endpoint."""
+ if endpoint.startswith('http'):
+ return endpoint
+ return urljoin(self.base_url + '/', endpoint.lstrip('/'))
+
+ def _handle_response(self, response: requests.Response) -> Dict[str, Any]:
+ """
+ Handle API response with error checking.
+
+ Args:
+ response: Response object from requests
+
+ Returns:
+ Parsed JSON response or empty dict
+
+ Raises:
+ RateLimitError: When rate limited
+ APIError: For other API errors
+ """
+ # Log response details
+ logger.debug(f"Response: {response.status_code} {response.url}")
+
+ # Handle rate limiting
+ if response.status_code == 429:
+ retry_after = response.headers.get('Retry-After')
+ if retry_after:
+ try:
+ retry_after = int(retry_after)
+ except ValueError:
+ retry_after = 60
+ raise RateLimitError(
+ "Rate limit exceeded",
+ retry_after=retry_after
+ )
+
+ # Handle errors
+ if not response.ok:
+ try:
+ error_body = response.json()
+ except:
+ error_body = {'message': response.text}
+
+ raise APIError(
+ f"API error: {response.status_code}",
+ status_code=response.status_code,
+ response=error_body
+ )
+
+ # Parse response
+ if response.status_code == 204:
+ return {}
+
+ try:
+ return response.json()
+ except:
+ return {'text': response.text}
+
+ def _request(
+ self,
+ method: str,
+ endpoint: str,
+ params: Optional[Dict[str, Any]] = None,
+ data: Optional[Dict[str, Any]] = None,
+ json_data: Optional[Dict[str, Any]] = None,
+ headers: Optional[Dict[str, str]] = None,
+ files: Optional[Dict[str, Any]] = None,
+ timeout: Optional[int] = None,
+ ) -> Dict[str, Any]:
+ """
+ Make an HTTP request.
+
+ Args:
+ method: HTTP method (GET, POST, PUT, PATCH, DELETE)
+ endpoint: API endpoint path
+ params: Query parameters
+ data: Form data
+ json_data: JSON body
+ headers: Additional headers
+ files: Files for multipart upload
+ timeout: Request timeout override
+
+ Returns:
+ Parsed response data
+ """
+ url = self._build_url(endpoint)
+ request_timeout = timeout or self.timeout
+
+ logger.info(f"{method} {url}")
+
+ try:
+ response = self.session.request(
+ method=method,
+ url=url,
+ params=params,
+ data=data,
+ json=json_data,
+ headers=headers,
+ files=files,
+ timeout=request_timeout,
+ )
+ return self._handle_response(response)
+
+ except RateLimitError:
+ raise
+ except APIError:
+ raise
+ except requests.Timeout:
+ raise APIError(f"Request timeout after {request_timeout}s")
+ except requests.ConnectionError as e:
+ raise APIError(f"Connection error: {e}")
+ except Exception as e:
+ logger.exception("Unexpected error")
+ raise APIError(f"Request failed: {e}")
+
+ # Convenience methods
+ def get(self, endpoint: str, **kwargs) -> Dict[str, Any]:
+ """Make a GET request."""
+ return self._request('GET', endpoint, **kwargs)
+
+ def post(self, endpoint: str, **kwargs) -> Dict[str, Any]:
+ """Make a POST request."""
+ return self._request('POST', endpoint, **kwargs)
+
+ def put(self, endpoint: str, **kwargs) -> Dict[str, Any]:
+ """Make a PUT request."""
+ return self._request('PUT', endpoint, **kwargs)
+
+ def patch(self, endpoint: str, **kwargs) -> Dict[str, Any]:
+ """Make a PATCH request."""
+ return self._request('PATCH', endpoint, **kwargs)
+
+ def delete(self, endpoint: str, **kwargs) -> Dict[str, Any]:
+ """Make a DELETE request."""
+ return self._request('DELETE', endpoint, **kwargs)
+
+ # =========================================================================
+ # API Endpoints - Add methods here based on HAR analysis
+ # =========================================================================
+
+ # Example: List resources
+ def list_resources(
+ self,
+ page: int = 1,
+ limit: int = 20,
+ filters: Optional[Dict[str, Any]] = None,
+ ) -> Dict[str, Any]:
+ """
+ List resources with pagination.
+
+ Args:
+ page: Page number (1-indexed)
+ limit: Items per page
+ filters: Optional filter parameters
+
+ Returns:
+ Dict with 'items' list and pagination info
+ """
+ params = {
+ 'page': page,
+ 'limit': limit,
+ }
+ if filters:
+ params.update(filters)
+
+ return self.get('/api/resources', params=params)
+
+ # Example: Get single resource
+ def get_resource(self, resource_id: str) -> Dict[str, Any]:
+ """
+ Get a resource by ID.
+
+ Args:
+ resource_id: The resource identifier
+
+ Returns:
+ Resource data
+ """
+ return self.get(f'/api/resources/{resource_id}')
+
+ # Example: Create resource
+ def create_resource(
+ self,
+ name: str,
+ description: Optional[str] = None,
+ **extra_fields,
+ ) -> Dict[str, Any]:
+ """
+ Create a new resource.
+
+ Args:
+ name: Resource name
+ description: Optional description
+ **extra_fields: Additional fields
+
+ Returns:
+ Created resource data
+ """
+ payload = {
+ 'name': name,
+ }
+ if description:
+ payload['description'] = description
+ payload.update(extra_fields)
+
+ return self.post('/api/resources', json_data=payload)
+
+ # Example: Update resource
+ def update_resource(
+ self,
+ resource_id: str,
+ **fields,
+ ) -> Dict[str, Any]:
+ """
+ Update a resource.
+
+ Args:
+ resource_id: The resource identifier
+ **fields: Fields to update
+
+ Returns:
+ Updated resource data
+ """
+ return self.patch(f'/api/resources/{resource_id}', json_data=fields)
+
+ # Example: Delete resource
+ def delete_resource(self, resource_id: str) -> bool:
+ """
+ Delete a resource.
+
+ Args:
+ resource_id: The resource identifier
+
+ Returns:
+ True if deleted successfully
+ """
+ self.delete(f'/api/resources/{resource_id}')
+ return True
+
+ # Example: Paginate through all resources
+ def iter_all_resources(
+ self,
+ limit: int = 100,
+ **filters,
+ ):
+ """
+ Iterate through all resources with automatic pagination.
+
+ Args:
+ limit: Items per page
+ **filters: Filter parameters
+
+ Yields:
+ Resource items one by one
+ """
+ page = 1
+ while True:
+ response = self.list_resources(page=page, limit=limit, filters=filters)
+
+ items = response.get('items', response.get('data', []))
+ if not items:
+ break
+
+ for item in items:
+ yield item
+
+ # Check if more pages
+ total = response.get('total', 0)
+ if page * limit >= total:
+ break
+
+ page += 1
+
+
+class RateLimitHandler:
+ """Helper class for handling rate limits with backoff."""
+
+ def __init__(self, client: APIClient):
+ self.client = client
+ self.last_retry_after = 0
+
+ def execute_with_retry(
+ self,
+ func,
+ *args,
+ max_retries: int = 3,
+ **kwargs,
+ ):
+ """
+ Execute a function with automatic rate limit retry.
+
+ Args:
+ func: Function to call (should be an API client method)
+ *args: Arguments for the function
+ max_retries: Maximum retry attempts
+ **kwargs: Keyword arguments for the function
+
+ Returns:
+ Function result
+ """
+ for attempt in range(max_retries):
+ try:
+ return func(*args, **kwargs)
+ except RateLimitError as e:
+ if attempt == max_retries - 1:
+ raise
+
+ wait_time = e.retry_after or (2 ** attempt * 10)
+ self.last_retry_after = wait_time
+ logger.warning(f"Rate limited. Waiting {wait_time}s before retry...")
+ time.sleep(wait_time)
+
+ raise APIError("Max retries exceeded")
+
+
+# ============================================================================
+# Example Usage
+# ============================================================================
+
+if __name__ == "__main__":
+ # Initialize client
+ client = APIClient(
+ base_url="https://api.example.com",
+ # api_key="your-api-key",
+ # access_token="your-bearer-token",
+ )
+
+ try:
+ # List resources
+ print("Fetching resources...")
+ response = client.list_resources(page=1, limit=10)
+ print(f"Found {len(response.get('items', []))} resources")
+
+ # Create a resource
+ # new_resource = client.create_resource(
+ # name="Test Resource",
+ # description="Created via API client"
+ # )
+ # print(f"Created: {new_resource}")
+
+ # Iterate all resources
+ # for resource in client.iter_all_resources():
+ # print(f"Resource: {resource['id']} - {resource['name']}")
+
+ except RateLimitError as e:
+ print(f"Rate limited! Retry after {e.retry_after}s")
+ except APIError as e:
+ print(f"API Error: {e} (status: {e.status_code})")
+ except Exception as e:
+ print(f"Error: {e}")
\ No newline at end of file