:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
feat(warehouse-sources): add help scout teams, organizations, fields and ratings (#121146)
Tom Owers3d7b99d3d41e
diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/COVERAGE_GAPS_APPENDIX.md b/products/warehouse_sources/backend/temporal/data_imports/sources/COVERAGE_GAPS_APPENDIX.mdindex e68d9325d681..2f6eed7d0319 100644--- a/products/warehouse_sources/backend/temporal/data_imports/sources/COVERAGE_GAPS_APPENDIX.md+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/COVERAGE_GAPS_APPENDIX.md@@ -5830,10 +5830,10 @@ Today (7): `conversations`, `customers`, `mailboxes`, `tags`, `threads`, `users`Diffed against: <https://developer.helpscout.com/mailbox-api/>-- [ ] `Organizations (GET /v2/organizations)` — resolve organizationId on customers to company names for account-level support analysis (high)-- [ ] `Teams (GET /v2/teams)` — identify support teams that receive conversations and compare team workloads (high)-- [ ] `Inbox custom fields (GET /v2/mailboxes/{mailboxId}/fields)` — resolve conversation field IDs and dropdown option IDs to names and labels (high)-- [ ] `Happiness Ratings Report (GET /v2/reports/happiness/ratings)` — measure customer satisfaction and connect ratings to support conversations and agents (high)+- [x] `Organizations (GET /v2/organizations)` — resolve organizationId on customers to company names for account-level support analysis (high)+- [x] `Teams (GET /v2/teams)` — identify support teams that receive conversations and compare team workloads (high)+- [x] `Inbox custom fields (GET /v2/mailboxes/{mailboxId}/fields)` — resolve conversation field IDs and dropdown option IDs to names and labels (high)+- [x] `Happiness Ratings Report (GET /v2/reports/happiness/ratings)` — measure customer satisfaction and connect ratings to support conversations and agents (high)- [ ] `Team members (GET /v2/teams/{teamId}/members)` — join agents to teams for staffing, workload, and performance comparisons (medium)- [ ] `Productivity Overall Report (GET /v2/reports/productivity)` — compare response times, resolution times, and support productivity with the vendor's reported metrics (medium)- [ ] `User Conversation History (GET /v2/reports/user/conversation-history)` — measure each agent's participation in conversations beyond the current assigned agent (medium)diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/helpscout/canonical_descriptions.py b/products/warehouse_sources/backend/temporal/data_imports/sources/helpscout/canonical_descriptions.pyindex d4bce5146de3..6f28952e752c 100644--- a/products/warehouse_sources/backend/temporal/data_imports/sources/helpscout/canonical_descriptions.py+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/helpscout/canonical_descriptions.py@@ -102,4 +102,66 @@ CANONICAL_DESCRIPTIONS: CanonicalDescriptions = {"modifiedAt": "Time the workflow was last modified, in ISO 8601 format.",},},+ "mailbox_fields": {+ "description": "A custom field defined on a mailbox (inbox), with its dropdown options.",+ "docs_url": "https://developer.helpscout.com/mailbox-api/endpoints/inboxes/inbox-fields/",+ "columns": {+ "id": "Unique identifier for the custom field.",+ "mailbox_id": "ID of the mailbox the custom field belongs to.",+ "name": "Name of the custom field, as seen in the Help Scout app.",+ "type": "Type of the custom field.",+ "required": "Whether the custom field must be set.",+ "order": "Display order of the custom field in the Help Scout app.",+ "options": "Dropdown options, each with an id, a display order, and a label.",+ "systemType": "System feature that owns the field (topic or sentiment). Absent for user-created fields.",+ },+ },+ "organizations": {+ "description": "A company that customers belong to.",+ "docs_url": "https://developer.helpscout.com/mailbox-api/endpoints/organizations/list/",+ "columns": {+ "id": "Unique identifier for the organization.",+ "name": "Organization name.",+ "website": "Organization website.",+ "description": "Organization description.",+ "location": "Organization location.",+ "logoUrl": "URL of the organization logo.",+ "note": "Free-text note about the organization.",+ "domains": "Email domains that belong to the organization.",+ "phones": "Phone numbers of the organization.",+ "brandColor": "Brand color of the organization, as a hex code.",+ },+ },+ "teams": {+ "description": "A team of users that conversations can be assigned to.",+ "docs_url": "https://developer.helpscout.com/mailbox-api/endpoints/teams/list-teams/",+ "columns": {+ "id": "Unique identifier for the team.",+ "name": "Team name.",+ "initials": "Team initials.",+ "mention": "Handle used to @mention the team in a thread body.",+ "timezone": "Team timezone.",+ "photoUrl": "URL of the team photo, if one exists.",+ "createdAt": "Time the team was created, in ISO 8601 format.",+ "updatedAt": "Time the team was last modified, in ISO 8601 format.",+ },+ },+ "happiness_ratings": {+ "description": "A happiness rating a customer left on a reply in a conversation.",+ "docs_url": "https://developer.helpscout.com/mailbox-api/endpoints/reports/happiness/reports-happiness-ratings/",+ "columns": {+ "id": "ID of the rated conversation.",+ "number": "Number of the rated conversation.",+ "type": "Conversation type: email, chat, or phone.",+ "threadid": "ID of the rated thread.",+ "threadCreatedAt": "Time the conversation was created, in ISO 8601 format.",+ "ratingId": "Rating value: 1 is Great, 2 is OK, 3 is Not Good.",+ "ratingComments": "Comments the customer left with the rating, if any.",+ "ratingCreatedAt": "Time the rating was created, in ISO 8601 format.",+ "ratingCustomerId": "ID of the customer who left the rating.",+ "ratingCustomerName": "Name of the customer who left the rating.",+ "ratingUserId": "ID of the user the rating is for.",+ "ratingUserName": "Name of the user the rating is for.",+ },+ },}diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/helpscout/helpscout.py b/products/warehouse_sources/backend/temporal/data_imports/sources/helpscout/helpscout.pyindex c0574dd3fcb3..f24b7b49dc47 100644--- a/products/warehouse_sources/backend/temporal/data_imports/sources/helpscout/helpscout.py+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/helpscout/helpscout.py@@ -1,5 +1,6 @@-from datetime import UTC, date, datetime+from datetime import UTC, date, datetime, timedeltafrom typing import Any, Optional, cast+from urllib.parse import urlencodefrom posthog.dataclasses import frozen@@ -14,6 +15,7 @@ from products.warehouse_sources.backend.temporal.data_imports.sources.common.res)from products.warehouse_sources.backend.temporal.data_imports.sources.common.rest_source.paginators import (JSONResponsePaginator,+ PageNumberPaginator,)from products.warehouse_sources.backend.temporal.data_imports.sources.common.rest_source.resource import Resourcefrom products.warehouse_sources.backend.temporal.data_imports.sources.common.rest_source.typing import ClientConfig@@ -33,11 +35,16 @@ from products.warehouse_sources.backend.temporal.data_imports.sources.helpscout.# self-contained (carries its own query string), so it's all we ever need to persist or send._NEXT_URL_PATH = "_links.next.href"+# Reports require a `start`. Help Scout launched in 2011, so no report data predates this.+_REPORT_WINDOW_START = "2011-01-01T00:00:00Z"+_AUTH_ERROR = ("Help Scout authentication failed. Check your client ID and client secret, and confirm the ""app has an active user invited to your Help Scout account.")+_REPORTS_PLAN_ERROR = "Help Scout reports are only available on the Plus and Pro plans."+@frozenclass HelpScoutResumeConfig:@@ -46,6 +53,10 @@ class HelpScoutResumeConfig:# Fan-out (threads): the framework's dependent-resource resume state# (`{"completed": [...], "current": ..., "child_state": ...}`).fanout_state: Optional[dict[str, Any]] = None+ # Reports: the next page number, and the window end the earlier attempt used, so a resumed+ # sync pages through the same window.+ page: Optional[int] = None+ report_end: str = ""def _uses_v3_route(config: HelpScoutEndpointConfig, api_version: str) -> bool:@@ -115,6 +126,50 @@ def _list_params(return {"sortField": config.partition_key or "createdAt", "sortOrder": "asc"}+def _report_resource(+ client_config: ClientConfig,+ config: HelpScoutEndpointConfig,+ team_id: int,+ job_id: str,+ resumable_source_manager: ResumableSourceManager[HelpScoutResumeConfig],+) -> Resource:+ report_end = _format_since(datetime.now(UTC))+ initial_paginator_state: Optional[dict[str, Any]] = None+ if resumable_source_manager.can_resume():+ resume = resumable_source_manager.load_state()+ if resume is not None and resume.page is not None and resume.report_end:+ report_end = resume.report_end+ initial_paginator_state = {"page": resume.page}++ rest_config: RESTAPIConfig = {+ "client": client_config,+ "resources": [+ {+ "name": config.name,+ "endpoint": {+ "path": config.path,+ "params": {**config.params, "start": _REPORT_WINDOW_START, "end": report_end},+ "paginator": PageNumberPaginator(base_page=1, total_path="pages"),+ "data_selector": config.embedded_key,+ },+ }+ ],+ }++ def save_checkpoint(state: Optional[dict[str, Any]]) -> None:+ if state and state.get("page") is not None:+ resumable_source_manager.save_state(HelpScoutResumeConfig(page=state["page"], report_end=report_end))++ return rest_api_resource(+ rest_config,+ team_id,+ job_id,+ None,+ resume_hook=save_checkpoint,+ initial_paginator_state=initial_paginator_state,+ )++def _top_level_resource(client_config: ClientConfig,config: HelpScoutEndpointConfig,@@ -133,13 +188,16 @@ def _top_level_resource("name": config.name,"endpoint": {"path": config.path,- "params": _list_params(- config,- use_v3_route,- should_use_incremental_field,- incremental_field,- db_incremental_field_last_value,- ),+ "params": {+ **config.params,+ **_list_params(+ config,+ use_v3_route,+ should_use_incremental_field,+ incremental_field,+ db_incremental_field_last_value,+ ),+ },"data_selector": f"_embedded.{config.embedded_key}",},}@@ -168,14 +226,15 @@ def _top_level_resource()-def _threads_resource(+def _fanout_resource(client_config: ClientConfig,+ config: HelpScoutEndpointConfig,team_id: int,job_id: str,resumable_source_manager: ResumableSourceManager[HelpScoutResumeConfig],) -> Resource:- threads_config = HELP_SCOUT_ENDPOINTS["threads"]- assert threads_config.fanout is not None+ assert config.fanout is not None+ parent_config = HELP_SCOUT_ENDPOINTS[config.fanout.parent_name]initial_paginator_state: Optional[dict[str, Any]] = Noneif resumable_source_manager.can_resume():@@ -191,8 +250,8 @@ def _threads_resource(Resource,build_dependent_resource(endpoint_configs=HELP_SCOUT_ENDPOINTS,- child_endpoint="threads",- fanout=threads_config.fanout,+ child_endpoint=config.name,+ fanout=config.fanout,client_config=client_config,path_format_values={},team_id=team_id,@@ -204,11 +263,11 @@ def _threads_resource(initial_paginator_state=initial_paginator_state,parent_endpoint_extra={"paginator": JSONResponsePaginator(next_url_path=_NEXT_URL_PATH),- "data_selector": "_embedded.conversations",+ "data_selector": f"_embedded.{parent_config.embedded_key}",},child_endpoint_extra={"paginator": JSONResponsePaginator(next_url_path=_NEXT_URL_PATH),- "data_selector": "_embedded.threads",+ "data_selector": f"_embedded.{config.embedded_key}",},),)@@ -230,7 +289,9 @@ def helpscout_source(client_config = _client_config(access_token, _api_base(config, api_version))if config.fanout:- resource: Resource = _threads_resource(client_config, team_id, job_id, resumable_source_manager)+ resource: Resource = _fanout_resource(client_config, config, team_id, job_id, resumable_source_manager)+ elif config.is_report:+ resource = _report_resource(client_config, config, team_id, job_id, resumable_source_manager)else:resource = _top_level_resource(client_config,@@ -282,19 +343,26 @@ def validate_credentials(config = HELP_SCOUT_ENDPOINTS.get(schema_name)if config is None:return False, f"Unknown Help Scout table '{schema_name}'"- # threads has no bare list endpoint (it's always scoped to a conversation); probe- # conversations instead, since that's the parent it fans out from.- probe_config = HELP_SCOUT_ENDPOINTS["conversations"] if config.fanout else config+ # Fan-out children have no bare list endpoint (threads are always scoped to a conversation);+ # probe the parent they fan out from instead.+ probe_config = HELP_SCOUT_ENDPOINTS[config.fanout.parent_name] if config.fanout else config+ probe_url = f"{_api_base(probe_config, api_version)}{probe_config.path}"+ if probe_config.is_report:+ # Reports reject a request without a window; a one-day window keeps the probe cheap.+ now = datetime.now(UTC)+ probe_url += "?" + urlencode({"start": _format_since(now - timedelta(days=1)), "end": _format_since(now)})# capture=False: same free-text-content rationale as `_client_config` above — the probed# endpoint can be `conversations`, whose responses carry customer-authored subjects.ok, status = validate_via_probe(lambda: make_tracked_session(redact_values=(access_token,), capture=False),- f"{_api_base(probe_config, api_version)}{probe_config.path}",+ probe_url,auth=auth,)if ok:return True, Noneif status == 401:return False, _AUTH_ERROR+ if status == 403 and probe_config.is_report:+ return False, _REPORTS_PLAN_ERRORreturn False, f"Help Scout API returned an unexpected status ({status}) while checking access to {schema_name}."diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/helpscout/settings.py b/products/warehouse_sources/backend/temporal/data_imports/sources/helpscout/settings.pyindex 96f3cffcc76d..c43ade578102 100644--- a/products/warehouse_sources/backend/temporal/data_imports/sources/helpscout/settings.py+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/helpscout/settings.py@@ -1,7 +1,7 @@"""Help Scout source settings and endpoint catalog."""from dataclasses import field-from typing import Optional+from typing import Any, Optionalfrom posthog.dataclasses import frozen@@ -22,7 +22,7 @@ HELP_SCOUT_API_BASE_V3 = "https://api.helpscout.net/v3"class HelpScoutEndpointConfig:name: strpath: str- # Key the rows live under inside the HAL `_embedded` object.+ # Key the rows live under inside the HAL `_embedded` object, or at the body root for reports.embedded_key: strprimary_key: list[str] = field(default_factory=lambda: ["id"])incremental_fields: list[IncrementalField] = field(default_factory=list)@@ -41,6 +41,10 @@ class HelpScoutEndpointConfig:# here since threads' fan-out passes `page_size_param=None` (Help Scout has no page-size param).page_size: int = 50fanout: Optional[DependentEndpointConfig] = None+ params: dict[str, Any] = field(default_factory=dict)+ # Reports return a plain JSON body (`results` with `page`/`pages`) instead of HAL, and require a+ # `start`/`end` window.+ is_report: bool = FalseHELP_SCOUT_ENDPOINTS: dict[str, HelpScoutEndpointConfig] = {@@ -100,6 +104,45 @@ HELP_SCOUT_ENDPOINTS: dict[str, HelpScoutEndpointConfig] = {parent_field_renames={"id": "conversation_id"},),),+ "mailbox_fields": HelpScoutEndpointConfig(+ name="mailbox_fields",+ path="/mailboxes/{mailbox_id}/fields",+ embedded_key="fields",+ # Field ids aren't documented as unique across mailboxes.+ primary_key=["mailbox_id", "id"],+ partition_key=None,+ fanout=DependentEndpointConfig(+ parent_name="mailboxes",+ resolve_param="mailbox_id",+ resolve_field="id",+ include_from_parent=["id"],+ parent_field_renames={"id": "mailbox_id"},+ ),+ ),+ "organizations": HelpScoutEndpointConfig(+ name="organizations",+ path="/organizations",+ embedded_key="organizations",+ partition_key=None,+ # The default sort is lastInteractionAt desc, which reorders rows while a sync paginates.+ params={"sort": "name,asc"},+ ),+ "teams": HelpScoutEndpointConfig(+ name="teams",+ path="/teams",+ embedded_key="teams",+ ),+ "happiness_ratings": HelpScoutEndpointConfig(+ name="happiness_ratings",+ path="/reports/happiness/ratings",+ embedded_key="results",+ # `id` is the conversation id and `ratingId` is the rating value, so the rated thread+ # identifies the row.+ primary_key=["id", "threadid"],+ partition_key="ratingCreatedAt",+ params={"sortField": "number", "sortOrder": "ASC"},+ is_report=True,+ ),}ENDPOINTS = tuple(HELP_SCOUT_ENDPOINTS.keys())diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/helpscout/source.py b/products/warehouse_sources/backend/temporal/data_imports/sources/helpscout/source.pyindex 40d6404744f8..f2635c418f23 100644--- a/products/warehouse_sources/backend/temporal/data_imports/sources/helpscout/source.py+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/helpscout/source.py@@ -69,6 +69,8 @@ class HelpScoutSource(OAuthMixin, ResumableSource[HelpScoutSourceConfig, HelpSco# Permanent token-exchange failures (invalid_client, inactive user, …) carry the# framework's stable marker; transient 429/5xx token errors don't."401 Client Error: Unauthorized for url: https://api.helpscout.net": "Help Scout authentication failed. Please reconnect your Help Scout account.",+ # Reports are gated to the Plus and Pro plans, which a retry can't change.+ "403 Client Error: Forbidden for url: https://api.helpscout.net/v2/reports": "Help Scout reports are only available on the Plus and Pro plans. Upgrade your Help Scout plan or deselect the happiness_ratings table.",# The linked OAuth integration was deleted while the source still references it.# Retrying can never resolve this, so ask the user to reconnect."Integration not found": "The linked Help Scout integration no longer exists. Please reconnect your Help Scout account.",diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/helpscout/tests/test_helpscout.py b/products/warehouse_sources/backend/temporal/data_imports/sources/helpscout/tests/test_helpscout.pyindex 5a8cdd55de4a..f62539578d46 100644--- a/products/warehouse_sources/backend/temporal/data_imports/sources/helpscout/tests/test_helpscout.py+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/helpscout/tests/test_helpscout.py@@ -96,6 +96,8 @@ class TestVersionRouting:("v3", "users", HELP_SCOUT_API_BASE),("v3", "tags", HELP_SCOUT_API_BASE),("v3", "workflows", HELP_SCOUT_API_BASE),+ ("v3", "organizations", HELP_SCOUT_API_BASE),+ ("v3", "teams", HELP_SCOUT_API_BASE),],)def test_request_url_follows_the_pinned_version(self, api_version: str, endpoint: str, base: str) -> None:@@ -223,11 +225,24 @@ class TestIncrementalParams:assert result.queries[0] == {}- @pytest.mark.parametrize("endpoint", ["mailboxes", "users", "tags", "workflows"])- def test_endpoints_without_sort_support_send_no_extra_params(self, endpoint: str) -> None:+ @pytest.mark.parametrize(+ "endpoint,expected_query",+ [+ ("mailboxes", {}),+ ("users", {}),+ ("tags", {}),+ ("workflows", {}),+ ("teams", {}),+ # The default lastInteractionAt sort reorders rows mid-sync, so a stable sort is sent.+ ("organizations", {"sort": ("name,asc",)}),+ ],+ )+ def test_endpoints_without_sort_support_send_only_static_params(+ self, endpoint: str, expected_query: dict[str, tuple[str, ...]]+ ) -> None:result = _run(endpoint, [_page(HELP_SCOUT_ENDPOINTS[endpoint].embedded_key, [])])- assert result.queries[0] == {}+ assert result.queries[0] == expected_queryclass TestRetries:@@ -249,24 +264,42 @@ class TestRetries:assert len(result.requests) == 1-class TestThreadsFanout:- @pytest.mark.parametrize("api_version,base", [("v2", HELP_SCOUT_API_BASE), ("v3", HELP_SCOUT_API_BASE_V3)])- def test_parent_and_child_endpoints(self, api_version: str, base: str) -> None:+class TestFanout:+ @pytest.mark.parametrize(+ "api_version,endpoint,parent,child_path,base",+ [+ ("v2", "threads", "conversations", "conversations/42/threads", HELP_SCOUT_API_BASE),+ ("v3", "threads", "conversations", "conversations/42/threads", HELP_SCOUT_API_BASE_V3),+ ("v2", "mailbox_fields", "mailboxes", "mailboxes/42/fields", HELP_SCOUT_API_BASE),+ # Mailbox fields have no v3 route, so a v3 pin keeps parent and child on v2.+ ("v3", "mailbox_fields", "mailboxes", "mailboxes/42/fields", HELP_SCOUT_API_BASE),+ ],+ )+ def test_parent_and_child_endpoints(+ self, api_version: str, endpoint: str, parent: str, child_path: str, base: str+ ) -> None:result = _run(- "threads",- [_page("conversations", [{"id": 42}]), _page("threads", [{"id": 7}])],+ endpoint,+ [_page(parent, [{"id": 42}]), _page(HELP_SCOUT_ENDPOINTS[endpoint].embedded_key, [{"id": 7}])],api_version=api_version,)assert result.raised is None- assert result.urls == [f"{base}/conversations", f"{base}/conversations/42/threads"]+ assert result.urls == [f"{base}/{parent}", f"{base}/{child_path}"]assert result.queries == [{}, {}]- def test_thread_rows_carry_the_parent_conversation_id(self) -> None:- result = _run("threads", [_page("conversations", [{"id": 42}]), _page("threads", [{"id": 7, "body": "hi"}])])+ @pytest.mark.parametrize(+ "endpoint,parent,parent_key",+ [("threads", "conversations", "conversation_id"), ("mailbox_fields", "mailboxes", "mailbox_id")],+ )+ def test_child_rows_carry_the_parent_id(self, endpoint: str, parent: str, parent_key: str) -> None:+ result = _run(+ endpoint,+ [_page(parent, [{"id": 42}]), _page(HELP_SCOUT_ENDPOINTS[endpoint].embedded_key, [{"id": 7, "x": "y"}])],+ )assert result.raised is None- assert result.rows == [{"conversation_id": 42, "id": 7, "body": "hi"}]+ assert result.rows == [{parent_key: 42, "id": 7, "x": "y"}]def test_resume_seeds_fanout_state(self) -> None:state = {"completed": ["/conversations/1/threads"], "current": None, "child_state": None}@@ -292,6 +325,46 @@ class TestThreadsFanout:)+def _report_page(results: list[dict[str, Any]], page: int, pages: int) -> ScriptedResponse:+ return ScriptedResponse(json={"facets": {}, "results": results, "page": page, "count": 0, "pages": pages})+++class TestHappinessRatingsReport:+ def test_walks_pages_until_the_last_page(self) -> None:+ result = _run(+ "happiness_ratings",+ [+ _report_page([{"id": 1, "threadid": 10}], page=1, pages=2),+ _report_page([{"id": 2, "threadid": 20}], page=2, pages=2),+ ],+ )++ assert result.raised is None+ assert [row["threadid"] for row in result.rows] == [10, 20]+ assert result.paths == ["/v2/reports/happiness/ratings", "/v2/reports/happiness/ratings"]+ assert [request.param("page") for request in result.requests] == ["1", "2"]+ first = result.requests[0]+ assert first.param("start") == "2011-01-01T00:00:00Z"+ assert first.param("end") is not None+ assert first.param("sortField") == "number"+ assert first.param("sortOrder") == "ASC"+ # The window end stays fixed across pages so page offsets don't shift mid-sync.+ assert result.requests[1].param("end") == first.param("end")+ assert result.saved_states == [HelpScoutResumeConfig(page=2, report_end=first.param("end") or "")]++ def test_resumes_from_saved_page_and_window(self) -> None:+ result = _run(+ "happiness_ratings",+ [_report_page([{"id": 3, "threadid": 30}], page=3, pages=3)],+ resume_state=HelpScoutResumeConfig(page=3, report_end="2024-05-01T00:00:00Z"),+ )++ assert result.raised is None+ assert result.requests[0].param("page") == "3"+ assert result.requests[0].param("end") == "2024-05-01T00:00:00Z"+ assert result.rows == [{"id": 3, "threadid": 30}]++class TestSourceResponseShape:@pytest.mark.parametrize("api_version,desc_endpoints",@@ -303,9 +376,9 @@ class TestSourceResponseShape:)def test_response_metadata_per_top_level_endpoint(self, api_version: str, desc_endpoints: dict[str, str]) -> None:for endpoint in ENDPOINTS:- if endpoint == "threads":- continueconfig = HELP_SCOUT_ENDPOINTS[endpoint]+ if config.fanout or config.is_report:+ continueresult = _run(endpoint, [_page(config.embedded_key, [])], api_version=api_version)response = result.response@@ -314,8 +387,8 @@ class TestSourceResponseShape:assert response.name == endpointassert response.primary_keys == config.primary_keyassert response.sort_mode == desc_endpoints.get(endpoint, "asc")- assert response.partition_mode == "datetime"- assert response.partition_keys == ["createdAt"]+ assert response.partition_mode == ("datetime" if config.partition_key else None)+ assert response.partition_keys == ([config.partition_key] if config.partition_key else None)def test_threads_response_uses_composite_primary_key(self) -> None:result = _run("threads", [_page("conversations", [])])@@ -377,6 +450,7 @@ class TestValidateCredentials:[("v2", "threads", f"{HELP_SCOUT_API_BASE}/conversations"),("v3", "threads", f"{HELP_SCOUT_API_BASE_V3}/conversations"),+ ("v3", "mailbox_fields", f"{HELP_SCOUT_API_BASE}/mailboxes"),("v3", "customers", f"{HELP_SCOUT_API_BASE_V3}/customers"),("v3", "mailboxes", f"{HELP_SCOUT_API_BASE}/mailboxes"),("v3", None, f"{HELP_SCOUT_API_BASE}/users/me"),@@ -390,3 +464,13 @@ class TestValidateCredentials:assert ok is Trueassert network.requests_log[0].url == expected_url++ def test_report_probe_sends_a_window_and_maps_403_to_the_plan_error(self) -> None:+ with scripted_network([ScriptedResponse(status=403)]) as network:+ ok, error = validate_credentials("token", "v3", schema_name="happiness_ratings")++ assert ok is False+ assert error is not None and "Plus and Pro" in error+ url = network.requests_log[0].url+ assert url.startswith(f"{HELP_SCOUT_API_BASE}/reports/happiness/ratings?start=")+ assert "&end=" in url