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.

6.4 KB
Raw Blame
from dataclasses import dataclass, field, replace
from typing import Literal, Optional

from products.warehouse_sources.sources.sdk import UNVERSIONED_API_VERSION, IncrementalField, IncrementalFieldType

VAPI_BASE_URL = "https://api.vapi.ai"

# Vapi's "v2" is a selective, per-resource scheme, not an account-wide or header-selected
# version: only some resources gained a distinct `/v2/<resource>` route, and the rest keep
# serving the same path and shape under both labels. Of the resources this source reads, only
# phone numbers diverge (see `version_overrides` below). `v1` is the legacy unversioned API
# existing rows are pinned to. See https://docs.vapi.ai/changelog/2025-09-17.
VAPI_VERSION_V1 = UNVERSIONED_API_VERSION
VAPI_VERSION_V2 = "v2"
SUPPORTED_VERSIONS = (VAPI_VERSION_V1, VAPI_VERSION_V2)
DEFAULT_VERSION = VAPI_VERSION_V2

# Vapi caps `limit` at 1000 (default 100). Call/chat objects can be large (full transcripts,
# message arrays, cost breakdowns), so keep pages at 100 rows to bound per-request memory.
DEFAULT_PAGE_LIMIT = 100

# How the endpoint paginates:
# - "created_at_cursor": returns a bare array in createdAt-descending order; the next page is
#   requested with `createdAtLt=<oldest createdAt of the previous page>`.
# - "page": returns a `{results, metadata}` envelope with `page`/`sortOrder`/`sortBy` params.
# - "none": returns the full collection in a single unpaginated array.
VapiPaginationStyle = Literal["created_at_cursor", "page", "none"]


def _datetime_incremental_field(name: str) -> IncrementalField:
    return {
        "label": name,
        "type": IncrementalFieldType.DateTime,
        "field": name,
        "field_type": IncrementalFieldType.DateTime,
    }


@dataclass(frozen=True)
class VapiEndpointVersion:
    """Per-version override of an endpoint's request path and pagination style, for a resource
    the vendor serves at a different route/shape under a newer API version."""

    path: str
    pagination: VapiPaginationStyle


@dataclass(frozen=False)
class VapiEndpointConfig:
    name: str
    path: str
    pagination: VapiPaginationStyle
    incremental_fields: list[IncrementalField] = field(default_factory=list)
    # Stable datetime field used for partitioning. None disables partitioning.
    partition_key: Optional[str] = "createdAt"
    primary_keys: list[str] = field(default_factory=lambda: ["id"])
    should_sync_default: bool = True
    # Versions that serve this resource at a different path/pagination than the version-
    # independent fields above, keyed by version label. Everything else (incremental fields,
    # partitioning, primary keys) is identical across versions for the resources we read.
    version_overrides: dict[str, VapiEndpointVersion] = field(default_factory=dict)


VAPI_ENDPOINTS: dict[str, VapiEndpointConfig] = {
    # Calls is the flagship stream: transcripts, analysis, ended reasons, durations, and cost
    # breakdowns. createdAt is the safe default cursor; updatedAt also has a server-side filter
    # (`updatedAtGt`) and re-syncs calls whose analysis/artifacts were attached after the call ended.
    "calls": VapiEndpointConfig(
        name="calls",
        path="/call",
        pagination="created_at_cursor",
        incremental_fields=[
            _datetime_incremental_field("createdAt"),
            _datetime_incremental_field("updatedAt"),
        ],
    ),
    # Assistants/phone numbers/squads/tools are small config tables that mutate in place, so a
    # createdAt watermark would go stale immediately; full refresh keeps them correct and cheap.
    "assistants": VapiEndpointConfig(
        name="assistants",
        path="/assistant",
        pagination="created_at_cursor",
    ),
    "phone_numbers": VapiEndpointConfig(
        name="phone_numbers",
        path="/phone-number",
        pagination="created_at_cursor",
        version_overrides={
            # v2 replaces the bare createdAt-descending array at /phone-number with a
            # page-numbered {results, metadata} envelope served at /v2/phone-number.
            VAPI_VERSION_V2: VapiEndpointVersion(path="/v2/phone-number", pagination="page"),
        },
    ),
    "squads": VapiEndpointConfig(
        name="squads",
        path="/squad",
        pagination="created_at_cursor",
    ),
    "tools": VapiEndpointConfig(
        name="tools",
        path="/tool",
        pagination="created_at_cursor",
    ),
    # GET /file takes no pagination params at all — single unpaginated array.
    "files": VapiEndpointConfig(
        name="files",
        path="/file",
        pagination="none",
        partition_key=None,
    ),
    # Page-based endpoints are requested with sortOrder=ASC&sortBy=createdAt so rows arrive in
    # ascending createdAt order. Only createdAt is offered as an incremental field: the API can't
    # sort by updatedAt, and an updatedAt watermark over createdAt-ordered pages would checkpoint
    # values that later pages can undercut, losing rows on the next sync.
    "chats": VapiEndpointConfig(
        name="chats",
        path="/chat",
        pagination="page",
        incremental_fields=[_datetime_incremental_field("createdAt")],
    ),
    "sessions": VapiEndpointConfig(
        name="sessions",
        path="/session",
        pagination="page",
        incremental_fields=[_datetime_incremental_field("createdAt")],
    ),
    # Run status and itemCounts change until the run ends, and the API can't sort by updatedAt, so
    # a createdAt watermark would freeze in-flight runs; the table is small, so full refresh only.
    "simulation_runs": VapiEndpointConfig(
        name="simulation_runs",
        path="/eval/simulation/run",
        pagination="page",
    ),
    # Campaigns mutate heavily (status plus per-call counters), so createdAt-incremental would go
    # stale immediately; the table is small, so full refresh only.
    "campaigns": VapiEndpointConfig(
        name="campaigns",
        path="/campaign",
        pagination="page",
    ),
}

ENDPOINTS = tuple(VAPI_ENDPOINTS.keys())


def resolve_endpoint(endpoint: str, api_version: str) -> VapiEndpointConfig:
    """Endpoint config for a resolved version pin, swapping in any per-version path/pagination."""
    config = VAPI_ENDPOINTS[endpoint]
    override = config.version_overrides.get(api_version)
    if override is None:
        return config
    return replace(config, path=override.path, pagination=override.pagination)


INCREMENTAL_FIELDS: dict[str, list[IncrementalField]] = {
    name: config.incremental_fields for name, config in VAPI_ENDPOINTS.items()
}