Skip to content

: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.

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.md
index 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.py
index 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.py
index 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, timedelta
from typing import Any, Optional, cast
+from urllib.parse import urlencode
from 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 Resource
from 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."
+
@frozen
class 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]] = None
if 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, None
if status == 401:
return False, _AUTH_ERROR
+ if status == 403 and probe_config.is_report:
+ return False, _REPORTS_PLAN_ERROR
return 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.py
index 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, Optional
from posthog.dataclasses import frozen
@@ -22,7 +22,7 @@ HELP_SCOUT_API_BASE_V3 = "https://api.helpscout.net/v3"
class HelpScoutEndpointConfig:
name: str
path: 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: str
primary_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 = 50
fanout: 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 = False
HELP_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.py
index 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.py
index 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_query
class 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":
- continue
config = HELP_SCOUT_ENDPOINTS[endpoint]
+ if config.fanout or config.is_report:
+ continue
result = _run(endpoint, [_page(config.embedded_key, [])], api_version=api_version)
response = result.response
@@ -314,8 +387,8 @@ class TestSourceResponseShape:
assert response.name == endpoint
assert response.primary_keys == config.primary_key
assert 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 True
assert 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