feat!: return full FetchResponse from context.fetch() (#20)

* Return full FetchResponse from context.fetch() (#12)

Add FetchResponse dataclass (status, headers, data) and update
ExecutionContext.fetch() to return it instead of the raw parsed body.
Export FetchResponse from the package.

* Update docs and samples for FetchResponse (#12)

Update all code examples, docstrings, and prose to use response.data
instead of the raw response body, reflecting the new FetchResponse
return type from context.fetch().

* Add migration plan for FetchResponse rollout (#12)

* Complete migration plan with full file inventory (#12)

Add 43 missing production files and 13 test files to the
autohive-integrations audit list.

* fix: restore ActionError in public exports

* docs: update remaining response → response.data in README_PYPI and ActionError example

* docs: add ActionError, FetchResponse, HTTPError/RateLimitError to module docstring

* Update apidocs for 2.0.0

* Add API docs maintenance guidelines to RELEASING.md and AGENTS.md

Author: TheRealAgentK

AGENTS.md

@@ -0,0 +1,16 @@
+# Agents Guidelines — Integrations SDK
+
+## API Documentation
+
+- API docs are generated with `pdoc` and live in `docs/apidocs/`.
+- These files are **tracked in version control** — do not add them to `.gitignore`.
+- Regenerate whenever the public API surface changes (new/modified classes, functions, or docstrings in `src/autohive_integrations_sdk/`):
+  ```
+  pdoc -o docs/apidocs src/autohive_integrations_sdk
+  ```
+- Always commit the regenerated docs alongside the code changes that caused them.
+
+## Releasing
+
+- Follow the process in [RELEASING.md](RELEASING.md).
+- API docs must be regenerated and committed before a release.

README_PYPI.md

@@ -29,7 +29,7 @@ class FetchData(ActionHandler):
             "https://api.example.com/data",
             headers={"Authorization": f"Bearer {context.auth['api_key']}"}
         )
-        return ActionResult(data=response)
+        return ActionResult(data=response.data)
 ```
 
 ## Key Features

RELEASING.md

@@ -32,7 +32,14 @@
     * Building wheel...
     Successfully built autohive_integrations_sdk-<a.b.c>.tar.gz and autohive_integrations_sdk-<a.b.c>-py3-none-any.whl
     ```
-    Upload:
+* Regenerate API docs:
+    - `pdoc` is required (`python3 -m pip install --upgrade pdoc`)
+    ```
+    pdoc -o docs/apidocs src/autohive_integrations_sdk
+    ```
+    - Commit the updated `docs/apidocs/` files — these are tracked in version control.
+
+* Release to PyPi — Upload:
     ```
     # Upload to PyPi, use API token from our secrets management
     python3 -m twine upload dist/autohive_integrations_sdk-<a.b.c>*

docs/apidocs/autohive_integrations_sdk.html

@@ -51,13 +51,14 @@ <h1 class="modulename">
                         <label class="view-source-button" for="mod-autohive_integrations_sdk-view-source"><span>View Source</span></label>
 
                         <div class="pdoc-code codehilite"><pre><span></span><span id="L-1"><a href="#L-1"><span class="linenos">1</span></a><span class="c1"># Version</span>
-</span><span id="L-2"><a href="#L-2"><span class="linenos">2</span></a><span class="n">__version__</span> <span class="o">=</span> <span class="s2">&quot;1.0.2&quot;</span>
+</span><span id="L-2"><a href="#L-2"><span class="linenos">2</span></a><span class="n">__version__</span> <span class="o">=</span> <span class="s2">&quot;1.1.1&quot;</span>
 </span><span id="L-3"><a href="#L-3"><span class="linenos">3</span></a>
 </span><span id="L-4"><a href="#L-4"><span class="linenos">4</span></a><span class="c1"># Re-export classes from integration module</span>
 </span><span id="L-5"><a href="#L-5"><span class="linenos">5</span></a><span class="kn">from</span><span class="w"> </span><span class="nn">autohive_integrations_sdk.integration</span><span class="w"> </span><span class="kn">import</span> <span class="p">(</span>
 </span><span id="L-6"><a href="#L-6"><span class="linenos">6</span></a>    <span class="n">Integration</span><span class="p">,</span> <span class="n">ExecutionContext</span><span class="p">,</span> <span class="n">ActionHandler</span><span class="p">,</span> <span class="n">PollingTriggerHandler</span><span class="p">,</span> <span class="n">ConnectedAccountHandler</span><span class="p">,</span>
-</span><span id="L-7"><a href="#L-7"><span class="linenos">7</span></a>    <span class="n">ConnectedAccountInfo</span><span class="p">,</span> <span class="n">ValidationError</span><span class="p">,</span> <span class="n">ActionResult</span><span class="p">,</span> <span class="n">IntegrationResult</span><span class="p">,</span> <span class="n">ResultType</span>
-</span><span id="L-8"><a href="#L-8"><span class="linenos">8</span></a><span class="p">)</span>
+</span><span id="L-7"><a href="#L-7"><span class="linenos">7</span></a>    <span class="n">ConnectedAccountInfo</span><span class="p">,</span> <span class="n">ValidationError</span><span class="p">,</span> <span class="n">HTTPError</span><span class="p">,</span> <span class="n">RateLimitError</span><span class="p">,</span> 
+</span><span id="L-8"><a href="#L-8"><span class="linenos">8</span></a>    <span class="n">ActionResult</span><span class="p">,</span> <span class="n">ActionError</span><span class="p">,</span> <span class="n">IntegrationResult</span><span class="p">,</span> <span class="n">ResultType</span><span class="p">,</span> <span class="n">FetchResponse</span>
+</span><span id="L-9"><a href="#L-9"><span class="linenos">9</span></a><span class="p">)</span>
 </span></pre></div>
 
 

docs/apidocs/autohive_integrations_sdk/integration.html

@@ -62,7 +62,7 @@ class CallApiAction(ActionHandler):
         response = await context.fetch(url, headers={"Authorization": f"Bearer {api_key}"})
 
         return ActionResult(
-            data={"result": response},
+            data={"result": response.data},
             cost_usd=0.05
         )
 ```
@@ -93,11 +93,11 @@ class GenerateContentAction(ActionHandler):
         )
 
         # Calculate cost based on usage returned by the API
-        tokens_used = response.get("usage", {}).get("total_tokens", 0)
+        tokens_used = response.data.get("usage", {}).get("total_tokens", 0)
         cost = tokens_used * 0.00001  # $0.01 per 1000 tokens
 
         return ActionResult(
-            data={"content": response["result"]},
+            data={"content": response.data["result"]},
             cost_usd=cost
         )
 ```

docs/apidocs/search.js

@@ -223,7 +223,7 @@ class GetItemsAction(ActionHandler):
                 params={"limit": limit}
             )
 
-            items = response.get("data", [])
+            items = response.data.get("data", [])
 
             return ActionResult(
                 data={
@@ -254,7 +254,7 @@ class GetItemsAction(ActionHandler):
 **`ActionHandler`** — Base class for all action handlers. You must implement the `async def execute()` method.
 
 **`ExecutionContext`** — Provided to every handler. Gives you:
-- `context.fetch(url, ...)` — Make HTTP requests with automatic auth handling
+- `context.fetch(url, ...)` — Make HTTP requests with automatic auth handling; returns a `FetchResponse` with `.status`, `.headers`, and `.data` attributes
 - `context.auth` — Access authentication credentials
 
 **`ActionResult`** — The required return type for all action handlers. Contains:
@@ -263,7 +263,7 @@ class GetItemsAction(ActionHandler):
 
 ### Making HTTP Requests
 
-Use `context.fetch()` for all HTTP calls. It handles authentication headers, retries, timeouts, and response parsing automatically.
+Use `context.fetch()` for all HTTP calls. It handles authentication headers, retries, timeouts, and response parsing automatically. It returns a `FetchResponse` object — access the parsed body via `.data`, the HTTP status via `.status`, and response headers via `.headers`.
 
 ```python
 # GET with query parameters
@@ -272,6 +272,7 @@ response = await context.fetch(
     method="GET",
     params={"limit": 10, "status": "active"}
 )
+items = response.data  # parsed response body
 
 # POST with JSON body
 response = await context.fetch(
@@ -280,6 +281,7 @@ response = await context.fetch(
     headers={"Content-Type": "application/json"},
     json={"name": "New Item", "status": "active"}
 )
+new_item = response.data
 
 # POST with form-encoded body
 response = await context.fetch(
@@ -288,6 +290,7 @@ response = await context.fetch(
     headers={"Content-Type": "application/x-www-form-urlencoded"},
     data={"name": "New Item"}
 )
+result = response.data
 ```
 
 ### Handling Inputs
@@ -325,7 +328,7 @@ class MyActionHandler(ActionHandler):
                 cost_usd=0.01  # API call was made, cost was still incurred
             )
 
-        return ActionResult(data=response)
+        return ActionResult(data=response.data)
 ```
 
 Use `ActionError` for expected, application-level failures. For unexpected infrastructure errors, let exceptions propagate normally.

docs/manual/billing.md

@@ -104,12 +104,13 @@ class MyConnectedAccountHandler(ConnectedAccountHandler):
         # Fetch user info from the API
         # For platform OAuth, context.fetch() auto-injects the Authorization header.
         # For custom auth, pass headers manually using context.auth.get("credentials", {}).get("api_key")
-        user_data = await context.fetch(
+        response = await context.fetch(
             "https://api.example.com/user",
             method="GET"
         )
 
         # Return ConnectedAccountInfo with available fields
+        user_data = response.data
         name = user_data.get("name", "")
         name_parts = name.split(maxsplit=1) if name else []
 
@@ -138,13 +139,14 @@ class GithubConnectedAccountHandler(ConnectedAccountHandler):
     async def get_account_info(self, context: ExecutionContext) -> ConnectedAccountInfo:
         """Fetch GitHub user information"""
         # context.fetch() auto-injects the Authorization header for platform OAuth
-        user_data = await context.fetch(
+        response = await context.fetch(
             "https://api.github.com/user",
             method="GET",
             headers={"Accept": "application/vnd.github.v3+json"}
         )
 
         # Parse name into first/last
+        user_data = response.data
         name = user_data.get("name", "")
         name_parts = name.split(maxsplit=1) if name else []
 
@@ -173,11 +175,12 @@ class LinkedInConnectedAccountHandler(ConnectedAccountHandler):
     async def get_account_info(self, context: ExecutionContext) -> ConnectedAccountInfo:
         """Fetch LinkedIn user information"""
         # context.fetch() auto-injects the Authorization header for platform OAuth
-        user_data = await context.fetch(
+        response = await context.fetch(
             "https://api.linkedin.com/v2/userinfo",
             method="GET"
         )
 
+        user_data = response.data
         return ConnectedAccountInfo(
             email=user_data.get("email"),
             first_name=user_data.get("given_name"),

docs/manual/building_your_first_integration.md

@@ -179,7 +179,7 @@ Required fields:
 Optional fields:
 - `scopes`: array of OAuth scopes to request
 
-With platform auth, `context.fetch()` automatically injects the `Authorization` header.
+With platform auth, `context.fetch()` automatically injects the `Authorization` header and returns a `FetchResponse` object (with `.status`, `.headers`, and `.data` attributes).
 
 #### No Auth