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(data-warehouse): add oncehub booking pages and availability tables (#123360)

Tom Owers9fab98df2a70
diff --git a/posthog/test/repo_invariants/dataclass_frozen_baseline.txt b/posthog/test/repo_invariants/dataclass_frozen_baseline.txt
index 2fac4dc7c2ce..d20ff919bc2e 100644
--- a/posthog/test/repo_invariants/dataclass_frozen_baseline.txt
+++ b/posthog/test/repo_invariants/dataclass_frozen_baseline.txt
@@ -811,8 +811,6 @@
1 products/warehouse_sources/backend/temporal/data_imports/sources/omni/omni.py
1 products/warehouse_sources/backend/temporal/data_imports/sources/omnisend/omnisend.py
1 products/warehouse_sources/backend/temporal/data_imports/sources/omnisend/settings.py
-1 products/warehouse_sources/backend/temporal/data_imports/sources/oncehub/oncehub.py
-1 products/warehouse_sources/backend/temporal/data_imports/sources/oncehub/settings.py
1 products/warehouse_sources/backend/temporal/data_imports/sources/onepagecrm/onepagecrm.py
1 products/warehouse_sources/backend/temporal/data_imports/sources/onepassword/onepassword.py
1 products/warehouse_sources/backend/temporal/data_imports/sources/onepassword/settings.py
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 06c442b4d975..7fe7ff6b1d98 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
@@ -8643,10 +8643,10 @@ Today (5): `booking_calendars`, `bookings`, `contacts`, `teams`, `users`
Diffed against: <https://developers.oncehub.com/booking-calendars-api.yaml>
-- [ ] `GET /v2/event-types (Booking Pages API)` — Lookup resolving the meeting type referenced by bookings — duration, location and conferencing per meeting, the natural breakdown dimension for booking volume (high)
-- [ ] `GET /v2/booking-pages (Booking Pages API)` — The classic-product equivalent of booking_calendars; accounts still on Booking Pages have bookings whose parent object is unresolvable today (high)
-- [ ] `GET /v2/master-pages (Booking Pages API)` — Groups booking pages into a single scheduling entry point — the rollup level teams actually report on (medium)
-- [ ] `GET /v2/users/{id}/scheduling-availability` — Per-user availability windows, the denominator for booked-hours-versus-available-hours utilization (low)
+- [x] `GET /v2/event-types (Booking Pages API)` — Lookup resolving the meeting type referenced by bookings — duration, location and conferencing per meeting, the natural breakdown dimension for booking volume (high)
+- [x] `GET /v2/booking-pages (Booking Pages API)` — The classic-product equivalent of booking_calendars; accounts still on Booking Pages have bookings whose parent object is unresolvable today (high)
+- [x] `GET /v2/master-pages (Booking Pages API)` — Groups booking pages into a single scheduling entry point — the rollup level teams actually report on (medium)
+- [x] `GET /v2/users/{id}/scheduling-availability` — Per-user availability windows, the denominator for booked-hours-versus-available-hours utilization (low)
Note: OnceHub publishes two parallel OpenAPI specs against the same /v2 base: booking-calendars-api.yaml (synced today) and booking-pages-api.yaml (the classic surface, https://developers.oncehub.com/booking-pages-api.yaml) — the latter is where event-types, booking-pages and master-pages live, and both share /bookings, /users, /teams and /contacts. Excluded: /webhooks, /notifications/sms, /one-time-links (ephemeral), /booking-calendars/{id}/time-slots (live availability query, not a warehouse table), and the write-only lifecycle actions (cancel, reassign, no-show, request-reschedule).
diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/oncehub/canonical_descriptions.py b/products/warehouse_sources/backend/temporal/data_imports/sources/oncehub/canonical_descriptions.py
index 60be4ed668cc..d7cf9f45941e 100644
--- a/products/warehouse_sources/backend/temporal/data_imports/sources/oncehub/canonical_descriptions.py
+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/oncehub/canonical_descriptions.py
@@ -2,7 +2,7 @@ from products.warehouse_sources.backend.temporal.data_imports.sources.common.can
CanonicalDescriptions,
)
-# Descriptions sourced from the OnceHub Booking Calendars API docs (https://developers.oncehub.com).
+# Descriptions sourced from the OnceHub Booking Calendars and Booking Pages API docs (https://developers.oncehub.com).
# Partial coverage is fine — uncovered columns fall back to LLM enrichment.
CANONICAL_DESCRIPTIONS: CanonicalDescriptions = {
"bookings": {
@@ -101,4 +101,46 @@ CANONICAL_DESCRIPTIONS: CanonicalDescriptions = {
"name": "The name of the team.",
},
},
+ "event_types": {
+ "description": "An event type (service) offered on classic Booking Pages. Bookings reference it through their event_type column.",
+ "docs_url": "https://help.oncehub.com/developers/api/booking-pages-api.yaml",
+ "columns": {
+ "id": "Unique identifier for the event type.",
+ "name": "The name of the event type.",
+ "description": "The description of the event type.",
+ },
+ },
+ "booking_pages": {
+ "description": "A classic Booking Page that customers use to schedule meetings. Bookings reference it through their booking_page column.",
+ "docs_url": "https://help.oncehub.com/developers/api/booking-pages-api.yaml",
+ "columns": {
+ "id": "Unique identifier for the booking page.",
+ "name": "The customer-facing name of the booking page.",
+ "label": "The internal label of the booking page.",
+ "url": "The URL of the booking page.",
+ "active": "True if this booking page is enabled and accepts bookings.",
+ "timezone": "The booking page timezone, in IANA format.",
+ },
+ },
+ "master_pages": {
+ "description": "A master page that groups several booking pages behind one scheduling entry point. Bookings reference it through their master_page column.",
+ "docs_url": "https://help.oncehub.com/developers/api/booking-pages-api.yaml",
+ "columns": {
+ "id": "Unique identifier for the master page.",
+ "name": "The customer-facing name of the master page.",
+ "label": "The internal label of the master page.",
+ "url": "The URL of the master page.",
+ "active": "True if this master page is enabled and accepts bookings.",
+ },
+ },
+ "user_scheduling_availability": {
+ "description": "The scheduling availability of each user: weekly working hours and date-specific overrides, one row per user.",
+ "docs_url": "https://help.oncehub.com/developers/api/booking-calendars-api.yaml",
+ "columns": {
+ "user_id": "The ID of the user this availability belongs to.",
+ "timezone": "The IANA timezone the working hours are expressed in.",
+ "weekly": "Recurring working hours per day of the week, with the meeting locations offered in each window.",
+ "overrides": "Date-specific working hours that replace the weekly hours. An empty list of working hours marks the date as unavailable.",
+ },
+ },
}
diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/oncehub/oncehub.py b/products/warehouse_sources/backend/temporal/data_imports/sources/oncehub/oncehub.py
index 3e11fe42e4b4..2a159fc37161 100644
--- a/products/warehouse_sources/backend/temporal/data_imports/sources/oncehub/oncehub.py
+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/oncehub/oncehub.py
@@ -1,5 +1,5 @@
import dataclasses
-from typing import Any, Optional
+from typing import Any, Optional, cast
from requests import Request, Response
@@ -8,16 +8,24 @@ from products.warehouse_sources.backend.temporal.data_imports.sources.common.res
RESTAPIConfig,
rest_api_resource,
)
-from products.warehouse_sources.backend.temporal.data_imports.sources.common.rest_source.paginators import BasePaginator
+from products.warehouse_sources.backend.temporal.data_imports.sources.common.rest_source.fanout import (
+ build_dependent_resource,
+)
+from products.warehouse_sources.backend.temporal.data_imports.sources.common.rest_source.paginators import (
+ BasePaginator,
+ SinglePagePaginator,
+)
+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
from products.warehouse_sources.backend.temporal.data_imports.sources.common.resumable import ResumableSourceManager
from products.warehouse_sources.backend.temporal.data_imports.sources.common.source_helpers import validate_via_probe
from products.warehouse_sources.backend.temporal.data_imports.sources.common.typings import SourceResponse
-from products.warehouse_sources.backend.temporal.data_imports.sources.oncehub.settings import ONCEHUB_ENDPOINTS
+from products.warehouse_sources.backend.temporal.data_imports.sources.oncehub.settings import (
+ ONCEHUB_ENDPOINTS,
+ OncehubEndpointConfig,
+)
ONCEHUB_BASE_URL = "https://api.oncehub.com/v2"
-# List endpoints accept a `limit` of 1-100 (default 10); the largest page minimises round trips
-# against OnceHub's tight 5 requests/second account rate limit.
-PAGE_SIZE = 100
# Cheap endpoint used to confirm an API key is genuine. The key is account-wide, so one probe
# validates access to every list endpoint.
DEFAULT_PROBE_PATH = "/users"
@@ -27,12 +35,15 @@ def _probe_headers(api_key: str) -> dict[str, str]:
return {"API-Key": api_key, "Accept": "application/json"}
[email protected](frozen=True)
class OncehubResumeConfig:
# Cursor for the next page: OnceHub paginates by passing the last item's object ID as `after`.
# A crashed full-refresh sync resumes from the page after the last one yielded; merge dedupes
# on `id`. `None` means start from the first page.
cursor: str | None = None
+ # `build_dependent_resource` checkpoint for fan-out endpoints (which parents finished, where the
+ # current one stopped), mutually exclusive with `cursor`.
+ fanout_state: dict[str, Any] | None = None
class OncehubCursorPaginator(BasePaginator):
@@ -81,31 +92,33 @@ class OncehubCursorPaginator(BasePaginator):
self._has_next_page = True
-def oncehub_source(
+def _client_config(api_key: str) -> ClientConfig:
+ return {
+ "base_url": ONCEHUB_BASE_URL,
+ # Only the non-secret Accept header goes here; the API key rides the framework auth config
+ # so it is redacted from logs and raised error messages.
+ "headers": {"Accept": "application/json"},
+ "auth": {"type": "api_key", "api_key": api_key, "name": "API-Key", "location": "header"},
+ "paginator": OncehubCursorPaginator(),
+ }
+
+
+def _list_resource(
api_key: str,
- endpoint: str,
+ config: OncehubEndpointConfig,
team_id: int,
job_id: str,
resumable_source_manager: ResumableSourceManager[OncehubResumeConfig],
- db_incremental_field_last_value: Optional[Any] = None,
-) -> SourceResponse:
- config = ONCEHUB_ENDPOINTS[endpoint]
-
+ db_incremental_field_last_value: Optional[Any],
+) -> Resource:
rest_config: RESTAPIConfig = {
- "client": {
- "base_url": ONCEHUB_BASE_URL,
- # Only the non-secret Accept header goes here; the API key rides the framework auth config
- # so it is redacted from logs and raised error messages.
- "headers": {"Accept": "application/json"},
- "auth": {"type": "api_key", "api_key": api_key, "name": "API-Key", "location": "header"},
- "paginator": OncehubCursorPaginator(),
- },
+ "client": _client_config(api_key),
"resources": [
{
- "name": endpoint,
+ "name": config.name,
"endpoint": {
"path": config.path,
- "params": {"limit": PAGE_SIZE},
+ "params": {"limit": config.page_size},
# OnceHub list endpoints wrap records in {"object": "list", "data": [...], "has_more": bool}.
"data_selector": "data",
# A 200 body that is not this envelope (missing `data`, or a bare/non-list payload)
@@ -128,7 +141,7 @@ def oncehub_source(
if state and state.get("cursor") is not None:
resumable_source_manager.save_state(OncehubResumeConfig(cursor=str(state["cursor"])))
- resource = rest_api_resource(
+ return rest_api_resource(
rest_config,
team_id,
job_id,
@@ -137,6 +150,68 @@ def oncehub_source(
initial_paginator_state=initial_paginator_state,
)
+
+def _fanout_resource(
+ api_key: str,
+ config: OncehubEndpointConfig,
+ team_id: int,
+ job_id: str,
+ resumable_source_manager: ResumableSourceManager[OncehubResumeConfig],
+ db_incremental_field_last_value: Optional[Any],
+) -> Resource:
+ assert config.fanout is not None
+ parent = ONCEHUB_ENDPOINTS[config.fanout.parent_name]
+
+ initial_fanout_state: Optional[dict[str, Any]] = None
+ if resumable_source_manager.can_resume():
+ resume = resumable_source_manager.load_state()
+ if resume is not None:
+ initial_fanout_state = resume.fanout_state
+
+ def save_fanout_checkpoint(state: Optional[dict[str, Any]]) -> None:
+ if state:
+ resumable_source_manager.save_state(OncehubResumeConfig(fanout_state=state))
+
+ return cast(
+ Resource,
+ build_dependent_resource(
+ endpoint_configs={config.name: config, parent.name: parent},
+ child_endpoint=config.name,
+ fanout=config.fanout,
+ client_config=_client_config(api_key),
+ path_format_values={},
+ team_id=team_id,
+ job_id=job_id,
+ db_incremental_field_last_value=db_incremental_field_last_value,
+ # OnceHub rejects unknown query params, so `limit` goes only to the parent listing
+ # (via `fanout.parent_params`), never to the single-object child request.
+ page_size_param=None,
+ parent_endpoint_extra={
+ "paginator": OncehubCursorPaginator(),
+ "data_selector": "data",
+ },
+ child_endpoint_extra={
+ "paginator": SinglePagePaginator(),
+ "data_selector": "$",
+ },
+ resume_hook=save_fanout_checkpoint,
+ initial_paginator_state=initial_fanout_state,
+ ),
+ )
+
+
+def oncehub_source(
+ api_key: str,
+ endpoint: str,
+ team_id: int,
+ job_id: str,
+ resumable_source_manager: ResumableSourceManager[OncehubResumeConfig],
+ db_incremental_field_last_value: Optional[Any] = None,
+) -> SourceResponse:
+ config = ONCEHUB_ENDPOINTS[endpoint]
+ build = _fanout_resource if config.fanout is not None else _list_resource
+ resource = build(api_key, config, team_id, job_id, resumable_source_manager, db_incremental_field_last_value)
+
return SourceResponse(
name=endpoint,
items=lambda: resource,
diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/oncehub/settings.py b/products/warehouse_sources/backend/temporal/data_imports/sources/oncehub/settings.py
index 162bc6f69976..9bc0f5f93edf 100644
--- a/products/warehouse_sources/backend/temporal/data_imports/sources/oncehub/settings.py
+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/oncehub/settings.py
@@ -1,16 +1,30 @@
from dataclasses import dataclass, field
+from typing import Any
+from products.warehouse_sources.backend.temporal.data_imports.sources.common.rest_source.fanout import (
+ DependentEndpointConfig,
+)
-@dataclass
+# List endpoints accept a `limit` of 1-100 (default 10); the largest page minimises round trips
+# against OnceHub's tight 5 requests/second account rate limit.
+PAGE_SIZE = 100
+
+
+@dataclass(frozen=True)
class OncehubEndpointConfig:
name: str
path: str
- # OnceHub object IDs are prefixed strings (BKNG-, CTC-, USR-, TM-, BKC-) that are unique
- # across the account, so `id` is a safe primary key for every endpoint.
+ # OnceHub object IDs are prefixed strings (BKNG-, CTC-, USR-, TM-, BKC-, MP-, ...) that are
+ # unique across the account, so `id` is a safe primary key for every list endpoint.
primary_keys: list[str] = field(default_factory=lambda: ["id"])
+ page_size: int = PAGE_SIZE
+ incremental_fields: list[Any] = field(default_factory=list)
+ default_incremental_field: str | None = None
+ fanout: DependentEndpointConfig | None = None
-# OnceHub Booking Calendars API (v2) list endpoints. All are full refresh only: the API's
+# OnceHub v2 list endpoints, from both the Booking Calendars API and the classic Booking Pages API
+# (event types, booking pages, master pages), which share one base URL and API key. All are full refresh only: the API's
# `last_updated_time.gt` filters are date-granular and list results paginate by object-ID cursor
# in reverse-chronological order, so there is no reliable server-side incremental cursor to
# advance safely without verified ordering guarantees.
@@ -20,6 +34,25 @@ ONCEHUB_ENDPOINTS: dict[str, OncehubEndpointConfig] = {
"contacts": OncehubEndpointConfig(name="contacts", path="/contacts"),
"users": OncehubEndpointConfig(name="users", path="/users"),
"teams": OncehubEndpointConfig(name="teams", path="/teams"),
+ "event_types": OncehubEndpointConfig(name="event_types", path="/event-types"),
+ "booking_pages": OncehubEndpointConfig(name="booking_pages", path="/booking-pages"),
+ "master_pages": OncehubEndpointConfig(name="master_pages", path="/master-pages"),
+ # One availability object per user, which carries no ID of its own, so the parent user ID keys it.
+ "user_scheduling_availability": OncehubEndpointConfig(
+ name="user_scheduling_availability",
+ path="/users/{id}/scheduling-availability",
+ primary_keys=["user_id"],
+ fanout=DependentEndpointConfig(
+ parent_name="users",
+ resolve_param="id",
+ resolve_field="id",
+ include_from_parent=["id"],
+ parent_field_renames={"id": "user_id"},
+ parent_params={"limit": PAGE_SIZE},
+ # A user deleted between the users listing and this fetch 404s; skip it instead of failing the sync.
+ child_response_actions=[{"status_code": 404, "action": "ignore"}],
+ ),
+ ),
}
ENDPOINTS = tuple(ONCEHUB_ENDPOINTS.keys())
diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/oncehub/source.py b/products/warehouse_sources/backend/temporal/data_imports/sources/oncehub/source.py
index 51a09e4409eb..254624b79049 100644
--- a/products/warehouse_sources/backend/temporal/data_imports/sources/oncehub/source.py
+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/oncehub/source.py
@@ -54,7 +54,7 @@ class OncehubSource(ResumableSource[OncehubSourceConfig, OncehubResumeConfig]):
keywords=["scheduleonce", "scheduling", "booking"],
caption="""Enter your OnceHub API key to pull your scheduling and booking data into the PostHog Data warehouse.
-You can generate an API key in [OnceHub](https://app.oncehub.com) under **Settings → API & Webhooks**. The key is shown only once at creation, so copy it right away. It grants read access to your bookings, booking calendars, contacts, users, and teams.
+You can generate an API key in [OnceHub](https://app.oncehub.com) under **Settings → API & Webhooks**. The key is shown only once at creation, so copy it right away. It grants read access to your bookings, booking calendars, booking pages, master pages, event types, contacts, users, and teams.
""",
iconPath="/static/services/oncehub.png",
docsUrl="https://posthog.com/docs/cdp/sources/oncehub",
diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/oncehub/tests/test_oncehub.py b/products/warehouse_sources/backend/temporal/data_imports/sources/oncehub/tests/test_oncehub.py
index 3e4e094b32b0..5b52d2602e28 100644
--- a/products/warehouse_sources/backend/temporal/data_imports/sources/oncehub/tests/test_oncehub.py
+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/oncehub/tests/test_oncehub.py
@@ -10,20 +10,17 @@ from products.warehouse_sources.backend.temporal.data_imports.sources.common.tes
ScriptedResponse,
SourceDriver,
always,
+ route,
scripted_network,
)
from products.warehouse_sources.backend.temporal.data_imports.sources.generated_configs.oncehub import (
OncehubSourceConfig,
)
from products.warehouse_sources.backend.temporal.data_imports.sources.oncehub.oncehub import (
- PAGE_SIZE,
OncehubResumeConfig,
validate_credentials,
)
-from products.warehouse_sources.backend.temporal.data_imports.sources.oncehub.settings import (
- ENDPOINTS,
- ONCEHUB_ENDPOINTS,
-)
+from products.warehouse_sources.backend.temporal.data_imports.sources.oncehub.settings import ENDPOINTS, PAGE_SIZE
from products.warehouse_sources.backend.temporal.data_imports.sources.oncehub.source import OncehubSource
@@ -132,8 +129,43 @@ class TestValidateCredentials:
assert {request.path for request in network.requests_log} == {"/v2/users"}
+class TestSchedulingAvailabilityFanout:
+ def test_fetches_availability_per_user_across_user_pages(self) -> None:
+ first_users = _full_page("USR")
+ availability = {"object": "schedule", "timezone": "America/Chicago", "weekly": [], "overrides": []}
+ result = _driver().run(
+ "user_scheduling_availability",
+ route(
+ {
+ "/v2/users": [
+ _response(first_users, has_more=True),
+ _response([{"id": "USR-final"}], has_more=False),
+ ],
+ "/scheduling-availability": [ScriptedResponse(json=availability)] * (PAGE_SIZE + 1),
+ }
+ ),
+ )
+
+ assert result.raised is None
+ assert len(result.rows) == PAGE_SIZE + 1
+ assert [row["user_id"] for row in result.rows] == [u["id"] for u in first_users] + ["USR-final"]
+ assert result.rows[0]["timezone"] == "America/Chicago"
+ assert not any(key.startswith("_users_") for key in result.rows[0])
+
+ user_list_requests = [r for r in result.requests if r.path == "/v2/users"]
+ assert [r.param("after") for r in user_list_requests] == [None, first_users[-1]["id"]]
+ assert {r.param("limit") for r in user_list_requests} == {str(PAGE_SIZE)}
+ # OnceHub rejects unknown query params, so the single-object child request must carry none.
+ child_requests = [r for r in result.requests if r.path.endswith("/scheduling-availability")]
+ assert child_requests[0].path == f"/v2/users/{first_users[0]['id']}/scheduling-availability"
+ assert all(not r.query for r in child_requests)
+ assert result.response is not None
+ assert result.response.primary_keys == ["user_id"]
+ assert result.response.partition_mode is None
+
+
class TestOncehubSourceResponse:
- @parameterized.expand([(e,) for e in ENDPOINTS])
+ @parameterized.expand([(e,) for e in ENDPOINTS if e != "user_scheduling_availability"])
def test_source_response_shape(self, endpoint: str) -> None:
result = _driver().run(endpoint, [_response([], has_more=False)])
@@ -143,7 +175,3 @@ class TestOncehubSourceResponse:
assert result.response.primary_keys == ["id"]
# Lists paginate newest-first with no stable ascending order, so we don't partition.
assert result.response.partition_mode is None
-
- def test_every_endpoint_uses_id_primary_key(self) -> None:
- assert all(config.primary_keys == ["id"] for config in ONCEHUB_ENDPOINTS.values())
- assert set(ONCEHUB_ENDPOINTS) == set(ENDPOINTS)