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

docs/manual/billing.md

@@ -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/manual/building_your_first_integration.md

@@ -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

docs/manual/connected_account.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/integration_structure.md

@@ -181,7 +181,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
 

docs/manual/patterns.md

@@ -24,7 +24,7 @@ class ListItemsAction(ActionHandler):
                 params=params
             )
 
-            items = response if isinstance(response, list) else response.get("data", [])
+            items = response.data if isinstance(response.data, list) else response.data.get("data", [])
             if not items:
                 break
 
@@ -62,10 +62,10 @@ class ListProjectsAction(ActionHandler):
                 params=params
             )
 
-            data = response.get("data", [])
+            data = response.data.get("data", [])
             all_projects.extend(data)
 
-            next_page = response.get("next_page")
+            next_page = response.data.get("next_page")
             if next_page and next_page.get("offset"):
                 offset = next_page["offset"]
             else:
@@ -93,9 +93,9 @@ class ListVideosAction(ActionHandler):
         response = await context.fetch(f"{BASE_URL}/videos", method="POST", json=request_body)
 
         return ActionResult(data={
-            "videos": response.get("videos", []),
-            "cursor": response.get("cursor"),
-            "has_more": response.get("has_more", False),
+            "videos": response.data.get("videos", []),
+            "cursor": response.data.get("cursor"),
+            "has_more": response.data.get("has_more", False),
         })
 ```
 
@@ -120,7 +120,7 @@ BASE_URL = f"https://api.example.com/{API_VERSION}"
 async def get_account_id(context: ExecutionContext) -> str:
     """Fetch the authenticated user's account ID."""
     response = await context.fetch(f"{BASE_URL}/me", method="GET")
-    account_id = response.get("id")
+    account_id = response.data.get("id")
     if not account_id:
         raise Exception("Failed to retrieve account ID")
     return account_id
@@ -164,7 +164,7 @@ class ExampleAPI:
 
         while True:
             response = await context.fetch(url, params=params, headers=headers)
-            items = response if isinstance(response, list) else []
+            items = response.data if isinstance(response.data, list) else []
             if not items:
                 break
             all_items.extend(items)

docs/plans/12.md

@@ -0,0 +1,200 @@
+# Issue #12 — FetchResponse Migration Plan
+
+> `context.fetch()` now returns a `FetchResponse` (with `.status`, `.headers`, `.data`)
+> instead of the raw parsed body. This is a **breaking change**.
+
+## SDK repo (integrations-sdk) — ✅ Done
+
+All changes committed on branch `issue-12/fetch-response`.
+
+### Implementation
+- [x] `src/autohive_integrations_sdk/integration.py` — `FetchResponse` dataclass + updated `fetch()` return type
+- [x] `src/autohive_integrations_sdk/__init__.py` — export `FetchResponse`
+
+### Docs & samples
+- [x] `docs/manual/billing.md`
+- [x] `docs/manual/building_your_first_integration.md`
+- [x] `docs/manual/connected_account.md`
+- [x] `docs/manual/integration_structure.md`
+- [x] `docs/manual/patterns.md`
+- [x] `samples/api-fetch/api_fetch.py`
+- [x] `samples/template/my_integration.py`
+
+### Not updated (generated)
+- `docs/apidocs/` — regenerate after merge with `pdoc`
+
+---
+
+## autohive-integrations (public) — 94 file hits
+
+Repo: `Autohive-AI/autohive-integrations`
+
+### Code (Python) — 81 production files, all need `response` → `response.data`
+- [ ] `api-call/api_call.py`
+- [ ] `app-business-reviews/app_business_reviews.py`
+- [ ] `asana/asana.py`
+- [ ] `bigquery/bigquery.py`
+- [ ] `bitly/bitly.py`
+- [ ] `box/box.py`
+- [ ] `calendly/calendly.py`
+- [ ] `canva/canva.py`
+- [ ] `circle/circle.py`
+- [ ] `clickup/clickup.py`
+- [ ] `coda/coda.py`
+- [ ] `companies-register/companies_register.py`
+- [ ] `dropbox/dropbox.py`
+- [ ] `elevenlabs/elevenlabs.py`
+- [ ] `eventbrite/eventbrite.py`
+- [ ] `facebook/actions/comments.py`
+- [ ] `facebook/actions/insights.py`
+- [ ] `facebook/actions/pages.py`
+- [ ] `facebook/actions/posts.py`
+- [ ] `facebook/helpers.py`
+- [ ] `fathom/fathom.py`
+- [ ] `float/float.py`
+- [ ] `freshdesk/freshdesk.py`
+- [ ] `front/front.py`
+- [ ] `github/github.py`
+- [ ] `gitlab/gitlab.py`
+- [ ] `gong/gong.py`
+- [ ] `google-calendar/google_calendar.py`
+- [ ] `google-docs/google_docs.py`
+- [ ] `google-looker/google_looker.py`
+- [ ] `google-tasks/google_tasks.py`
+- [ ] `hackernews/hackernews.py`
+- [ ] `harvest/harvest.py`
+- [ ] `heartbeat/heartbeat.py`
+- [ ] `heygen/heygen.py`
+- [ ] `humanitix/actions/checkin.py`
+- [ ] `humanitix/actions/events.py`
+- [ ] `humanitix/actions/orders.py`
+- [ ] `humanitix/actions/tags.py`
+- [ ] `humanitix/actions/tickets.py`
+- [ ] `humanitix/helpers.py`
+- [ ] `instagram/actions/account.py`
+- [ ] `instagram/actions/comments.py`
+- [ ] `instagram/actions/insights.py`
+- [ ] `instagram/actions/media.py`
+- [ ] `instagram/helpers.py`
+- [ ] `instagram/instagram.py`
+- [ ] `linkedin/linkedin.py`
+- [ ] `linkedin-ads/linkedin_ads.py`
+- [ ] `mailchimp/mailchimp.py`
+- [ ] `microsoft-excel/microsoft_excel.py`
+- [ ] `microsoft-planner/microsoft_planner.py`
+- [ ] `microsoft-powerpoint/microsoft_powerpoint.py`
+- [ ] `microsoft-word/microsoft_word.py`
+- [ ] `microsoft365/microsoft365.py`
+- [ ] `monday-com/monday_com.py`
+- [ ] `netlify/netlify.py`
+- [ ] `notion/notion.py`
+- [ ] `nzbn/nzbn.py`
+- [ ] `pipedrive/pipedrive.py`
+- [ ] `powerbi/powerbi.py`
+- [ ] `productboard/productboard.py`
+- [ ] `reddit/reddit.py`
+- [ ] `retail-express/retail_express.py`
+- [ ] `rss-reader-feedparser-ah-fetch/rss_reader.py`
+- [ ] `shopify-admin/shopify_admin.py`
+- [ ] `shopify-customer/shopify_customer.py`
+- [ ] `shopify-storefront/shopify_storefront.py`
+- [ ] `stripe/stripe.py`
+- [ ] `tiktok/tiktok.py`
+- [ ] `toggl/toggl.py`
+- [ ] `trello/trello.py`
+- [ ] `typeform/typeform.py`
+- [ ] `uber/uber.py`
+- [ ] `webcal/webcal.py`
+- [ ] `whatsapp/whatsapp.py`
+- [ ] `X/x.py`
+- [ ] `xero/xero.py`
+- [ ] `youtube/youtube.py`
+- [ ] `zoho/zoho.py`
+- [ ] `zoom/zoom.py`
+
+### Tests (Python) — 13 test files, mock return values need to return `FetchResponse`
+- [ ] `linkedin-ads/tests/test_linkedin_ads.py`
+- [ ] `microsoft-planner/tests/test_microsoft_planner.py`
+- [ ] `microsoft-powerpoint/tests/test_microsoft_powerpoint.py`
+- [ ] `microsoft-word/tests/test_microsoft_word.py`
+- [ ] `microsoft365/tests/test_microsoft365_integration.py`
+- [ ] `monday-com/tests/test_monday_com.py`
+- [ ] `notion/tests/test_notion_integration.py`
+- [ ] `powerbi/tests/test_powerbi_integration.py`
+- [ ] `productboard/tests/test_productboard.py`
+- [ ] `shopify-customer/tests/test_unit.py`
+- [ ] `uber/tests/test_uber.py`
+- [ ] `xero/tests/test_xero.py`
+- [ ] `zoom/tests/run_test.py`
+
+### Docs (Markdown)
+- [ ] `README.md`
+- [ ] `api-call/README.md`
+
+### Dependency
+- [ ] Bump `autohive-integrations-sdk` version in each integration's `requirements.txt`
+
+---
+
+## integrations (private) — 5 code hits
+
+Repo: `Autohive-AI/integrations`
+
+### Code (Python)
+- [ ] `discord/discord.py`
+- [ ] `hubspot/hubspot.py`
+- [ ] `perplexity/perplexity.py`
+- [ ] `slack/slack.py`
+- [ ] `telegram/telegram.py`
+
+### Dependency
+- [ ] Bump `autohive-integrations-sdk` version in each integration's `requirements.txt`
+
+---
+
+## Autohive (private/platform) — 2 code hits
+
+Repo: `Autohive-AI/Autohive`
+
+### Code (Python)
+- [ ] `integrations/github/github_integration.py`
+- [ ] `integrations/slack/slack.py`
+
+### Dependency
+- [ ] Bump `autohive-integrations-sdk` version in `requirements.txt`
+
+---
+
+## autohive-docs (private) — 1 doc hit
+
+Repo: `Autohive-AI/autohive-docs`
+
+### Docs (Markdown)
+- [ ] `content/docs/integrations/api-call.md`
+
+---
+
+## Release sequence
+
+1. Merge & release SDK (`integrations-sdk`) with new minor version
+2. Update `autohive-integrations` (public) — bulk PR for all integrations + docs
+3. Update `integrations` (private) — PR for 5 integrations
+4. Update `Autohive` (private) — PR for 2 integration files
+5. Update `autohive-docs` (private) — PR for api-call docs page
+6. Regenerate `docs/apidocs/` in SDK repo
+
+## Migration pattern
+
+Every call site follows the same mechanical change:
+
+```python
+# Before
+response = await context.fetch(url)
+data = response.get("key")           # or response["key"], etc.
+return ActionResult(data=response)
+
+# After
+response = await context.fetch(url)
+data = response.data.get("key")      # access body via .data
+return ActionResult(data=response.data)
+```