: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 quo contact notes table (#119542)
Tom Owers6ba1f8d33f77
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 4a5724c2fc24..1a4d3a4c64da 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@@ -9966,6 +9966,7 @@ Diffed against: <https://www.quo.com/docs/mdx/api-reference/openapi.md>- [ ] `Call transcriptions (GET /v1/call-transcripts/{id})` — analyze customer requests and call content alongside existing call records (medium)- [ ] `Call recordings (GET /v1/call-recordings/{callId})` — measure recording availability, segment duration, and processing failures for calls (medium)- [ ] `Call voicemails (GET /v1/call-voicemails/{callId})` — analyze missed-call messages and voicemail processing outcomes (medium)+- [x] `Contact notes (GET /contacts/{contactId}/notes)` — the notes your team keeps on each contact, joinable to the contacts table (medium)Note: The official v1 OpenAPI specification was fetched with curl and its GET operations were compared with both source version maps. Call artifacts need requests for each call, and transcripts require a Business or Scale plan. The dated calls table already requests summaries, so summaries are excluded as a general gap. Webhooks and write operations are excluded.diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/quo/canonical_descriptions.py b/products/warehouse_sources/backend/temporal/data_imports/sources/quo/canonical_descriptions.pyindex 320a0d2e1284..32b1261fa452 100644--- a/products/warehouse_sources/backend/temporal/data_imports/sources/quo/canonical_descriptions.py+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/quo/canonical_descriptions.py@@ -61,6 +61,19 @@ CANONICAL_DESCRIPTIONS: CanonicalDescriptions = {"type": "The data type of the custom contact field.",},},+ "contact_notes": {+ "description": "The notes your team left on contacts in your Quo workspace.",+ "docs_url": "https://www.quo.com/docs/2026-03-30/contact-notes/list-notes-for-a-contact",+ "columns": {+ "id": "The unique identifier of the note.",+ "contactId": "The unique identifier of the contact the note belongs to.",+ "text": "The body of the note.",+ "media": "The attachments on the note, each with a URL, MIME type and file name.",+ "actorId": "The unique identifier of the user who wrote the note.",+ "createdAt": "Timestamp of note creation, in ISO 8601 format.",+ "updatedAt": "Timestamp of last note update, in ISO 8601 format.",+ },+ },"conversations": {"description": "The call and message conversations in your Quo workspace, one per phone number and participant set.","docs_url": "https://www.quo.com/docs/mdx/api-reference/conversations/list-conversations",diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/quo/quo.py b/products/warehouse_sources/backend/temporal/data_imports/sources/quo/quo.pyindex 7176398a3544..3edbc2d8cb86 100644--- a/products/warehouse_sources/backend/temporal/data_imports/sources/quo/quo.py+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/quo/quo.py@@ -1,12 +1,16 @@from collections.abc import Callable, Iterable, Iteratorfrom typing import Any, Optional+from urllib.parse import quotefrom requests import Sessionfrom posthog.dataclasses import frozenfrom products.warehouse_sources.backend.temporal.data_imports.sources.common.datetime_utils import parse_datetime_value-from products.warehouse_sources.backend.temporal.data_imports.sources.common.http import make_tracked_session+from products.warehouse_sources.backend.temporal.data_imports.sources.common.http import (+ default_request_timeout,+ make_tracked_session,+)from products.warehouse_sources.backend.temporal.data_imports.sources.common.rest_source import (RESTAPIConfig,rest_api_resource,@@ -20,6 +24,8 @@ from products.warehouse_sources.backend.temporal.data_imports.sources.common.soufrom products.warehouse_sources.backend.temporal.data_imports.sources.common.typings import SourceResponsefrom products.warehouse_sources.backend.temporal.data_imports.sources.quo.settings import (DATED_ENDPOINTS_BY_VERSION,+ QUO_2026_03_30_ENDPOINTS,+ QUO_API_VERSION_2026_03_30,QUO_API_VERSION_HEADER,QUO_API_VERSION_V1,QUO_BASE_URL,@@ -34,6 +40,10 @@ class QuoResumeConfig:page_token: str# The dated version the cursor was issued under. None is the v1 wire, which pages with incompatible cursors.api_version: str | None = None+ # Contact notes only: the contact whose notes were last yielded, and its next notes page.+ # A None notes cursor means that contact is done.+ contact_id: str | None = None+ notes_cursor: str | None = Nonedef _to_iso(value: Any) -> Optional[str]:@@ -150,6 +160,87 @@ def _fan_out_rows(api_key: str, config: QuoEndpointConfig, params: dict[str, Any)+def _contact_notes_rows(+ api_key: str,+ config: QuoEndpointConfig,+ resumable_source_manager: ResumableSourceManager[QuoResumeConfig],+) -> Iterator[list[dict[str, Any]]]:+ """Fan contact notes out over the dated contacts list.++ Each staged cursor points just past the notes page it is staged with. Full refresh appends a+ resumed run's rows without a merge, so a resumed run must not read a written note again.+ """+ session = make_tracked_session(+ headers={**_auth_headers(api_key), QUO_API_VERSION_HEADER: QUO_API_VERSION_2026_03_30},+ redact_values=(api_key,),+ )+ contacts = QUO_2026_03_30_ENDPOINTS["contacts"]++ contacts_cursor: Optional[str] = None+ resume: Optional[QuoResumeConfig] = None+ if resumable_source_manager.can_resume():+ saved = resumable_source_manager.load_state()+ if saved is not None and saved.api_version == QUO_API_VERSION_2026_03_30:+ resume = saved+ contacts_cursor = saved.page_token or None++ while True:+ params: dict[str, Any] = {"limit": contacts.page_size}+ if contacts_cursor is not None:+ params["after"] = contacts_cursor+ response = session.get(f"{QUO_BASE_URL}{contacts.path}", params=params, timeout=default_request_timeout())+ response.raise_for_status()+ body = response.json()+ resumable_source_manager.safe_point()++ contact_ids = [contact["id"] for contact in body.get("data") or [] if contact.get("id")]+ start = 0+ notes_cursor: Optional[str] = None+ # A resume contact missing from the page was deleted, so the page is read from its start.+ if resume is not None and resume.contact_id in contact_ids:+ start = contact_ids.index(resume.contact_id)+ notes_cursor = resume.notes_cursor+ if notes_cursor is None:+ start += 1+ resume = None++ for contact_id in contact_ids[start:]:+ path = config.path.replace("{contactId}", quote(contact_id, safe=""))+ while True:+ notes_params: dict[str, Any] = {"limit": config.page_size}+ if notes_cursor is not None:+ notes_params["after"] = notes_cursor+ notes_response = session.get(+ f"{QUO_BASE_URL}{path}", params=notes_params, timeout=default_request_timeout()+ )+ # A contact deleted after the contacts page was read answers 404; its notes are gone too.+ if notes_response.status_code == 404:+ break+ notes_response.raise_for_status()+ notes_body = notes_response.json()+ notes = notes_body.get("data") or []+ notes_cursor = notes_body.get("nextCursor") or None+ if notes:+ resumable_source_manager.save_state(+ QuoResumeConfig(+ page_token=contacts_cursor or "",+ api_version=QUO_API_VERSION_2026_03_30,+ contact_id=contact_id,+ notes_cursor=notes_cursor,+ )+ )+ yield [{**note, "contactId": contact_id} for note in notes]+ else:+ resumable_source_manager.safe_point()+ if notes_cursor is None:+ break+ notes_cursor = None++ contacts_cursor = body.get("nextCursor")+ if not contacts_cursor:+ return++def _rest_source(api_key: str,name: str,@@ -219,7 +310,7 @@ def _source_response(endpoint: str, config: QuoEndpointConfig, items: Callable[[return SourceResponse(name=endpoint,items=items,- primary_keys=[config.primary_key],+ primary_keys=list(config.primary_keys),# Quo lists return newest-first and the fan-out restarts per conversation, so rows never# arrive globally ascending. "desc" defers the watermark commit to the end of a# successful sync instead of checkpointing it mid-run.@@ -247,6 +338,11 @@ def quo_source(dated_endpoints = _dated_endpoints(api_version)dated_config = dated_endpoints.get(endpoint) if dated_endpoints is not None else None+ if config.fan_out_over_contacts:+ return _source_response(+ endpoint, config, lambda: _contact_notes_rows(api_key, config, resumable_source_manager)+ )+last_value = db_incremental_field_last_value if should_use_incremental_field else Nonecursor_field = incremental_field or (config.incremental_fields[0]["field"] if config.incremental_fields else None)diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/quo/settings.py b/products/warehouse_sources/backend/temporal/data_imports/sources/quo/settings.pyindex a211f8b77c3f..d575f76cb324 100644--- a/products/warehouse_sources/backend/temporal/data_imports/sources/quo/settings.py+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/quo/settings.py@@ -25,7 +25,7 @@ DATED_PAGE_SIZE = 50class QuoEndpointConfig:name: strpath: str- primary_key: str = "id"+ primary_keys: tuple[str, ...] = ("id",)# None means the endpoint returns the full collection in one unpaginated response.page_size: int | None = Noneincremental_fields: list[IncrementalField] = field(default_factory=list)@@ -40,6 +40,9 @@ class QuoEndpointConfig:# /v1/calls serves one-to-one conversations only (`participants` caps at one number);# /v1/messages accepts the full participants array of a group conversation.supports_group_conversations: bool = True+ # Contact notes exist only under 2026-03-30 and list one contact at a time, so the endpoint+ # fans out over the dated contacts list under every pinned version.+ fan_out_over_contacts: bool = FalseQUO_ENDPOINTS: dict[str, QuoEndpointConfig] = {@@ -63,7 +66,7 @@ QUO_ENDPOINTS: dict[str, QuoEndpointConfig] = {"contact_custom_fields": QuoEndpointConfig(name="contact_custom_fields",path="/v1/contact-custom-fields",- primary_key="key",+ primary_keys=("key",),),"conversations": QuoEndpointConfig(name="conversations",@@ -92,6 +95,15 @@ QUO_ENDPOINTS: dict[str, QuoEndpointConfig] = {partition_key="createdAt",fan_out_over_conversations=True,),+ "contact_notes": QuoEndpointConfig(+ name="contact_notes",+ path="/contacts/{contactId}/notes",+ page_size=DATED_PAGE_SIZE,+ # Notes carry no contact reference, and Quo documents no global uniqueness for note IDs.+ primary_keys=("contactId", "id"),+ partition_key="createdAt",+ fan_out_over_contacts=True,+ ),}diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/quo/tests/test_quo.py b/products/warehouse_sources/backend/temporal/data_imports/sources/quo/tests/test_quo.pyindex 725d9d304197..59619426b853 100644--- a/products/warehouse_sources/backend/temporal/data_imports/sources/quo/tests/test_quo.py+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/quo/tests/test_quo.py@@ -261,6 +261,80 @@ class TestDatedVersion:assert result.requests == []+def _notes_state(contacts_cursor: str, contact_id: str, notes_cursor: str | None) -> QuoResumeConfig:+ return QuoResumeConfig(+ page_token=contacts_cursor, api_version="2026-03-30", contact_id=contact_id, notes_cursor=notes_cursor+ )+++class TestContactNotes:+ @pytest.mark.parametrize("api_version", [QUO_API_VERSION_V1, QUO_API_VERSION_2026_03_30])+ def test_fans_out_over_contacts_on_the_dated_wire(self, api_version):+ result = _source(+ "contact_notes",+ [+ _dated_page([{"id": "CT1"}, {"id": "CT2"}], next_cursor="c2"),+ _dated_page([{"id": "N1"}], next_cursor="n2"),+ _dated_page([{"id": "N2"}]),+ _dated_page([]),+ _dated_page([{"id": "CT3"}]),+ # CT3 was deleted after the contacts page was read.+ ScriptedResponse(status=404, json={"message": "Not Found"}),+ ],+ api_version=api_version,+ )++ assert result.raised is None+ assert [(row["contactId"], row["id"]) for row in result.rows] == [("CT1", "N1"), ("CT1", "N2")]+ assert result.paths == [+ "/contacts",+ "/contacts/CT1/notes",+ "/contacts/CT1/notes",+ "/contacts/CT2/notes",+ "/contacts",+ "/contacts/CT3/notes",+ ]+ assert result.params("after") == [None, None, "n2", None, "c2", None]+ assert {request.headers["quo-api-version"] for request in result.requests} == {"2026-03-30"}+ assert result.saved_states == [_notes_state("", "CT1", "n2"), _notes_state("", "CT1", None)]++ @pytest.mark.parametrize(+ "resume_state, expected_paths, expected_after",+ [+ (+ _notes_state("c5", "CT2", "n3"),+ ["/contacts", "/contacts/CT2/notes", "/contacts/CT3/notes"],+ ["c5", "n3", None],+ ),+ (+ _notes_state("c5", "CT1", None),+ ["/contacts", "/contacts/CT2/notes", "/contacts/CT3/notes"],+ ["c5", None, None],+ ),+ (+ _notes_state("c5", "CT0", None),+ ["/contacts", "/contacts/CT1/notes", "/contacts/CT2/notes", "/contacts/CT3/notes"],+ ["c5", None, None, None],+ ),+ (+ QuoResumeConfig(page_token="tok5"),+ ["/contacts", "/contacts/CT1/notes", "/contacts/CT2/notes", "/contacts/CT3/notes"],+ [None, None, None, None],+ ),+ ],+ )+ def test_resumes_after_the_last_written_notes_page(self, resume_state, expected_paths, expected_after):+ result = _source(+ "contact_notes",+ [_dated_page([{"id": "CT1"}, {"id": "CT2"}, {"id": "CT3"}]), *[_dated_page([]) for _ in range(3)]],+ resume_state=resume_state,+ )++ assert result.raised is None+ assert result.paths == expected_paths+ assert result.params("after") == expected_after++class TestQuoSourceResponse:def test_unknown_endpoint_raises_unknown_resource(self):result = _source("not_a_table", [])