: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
"""
Contract types for customer_analytics.
Stable, framework-free frozen dataclasses that define what this product exposes to
the rest of the codebase. No Django imports.
These use ``pydantic.dataclasses.dataclass`` rather than the stdlib variant — same
syntax and ``is_dataclass()`` compatibility, but with runtime validation on
construction, so structural mistakes from mappers surface at the facade boundary
instead of producing a malformed payload deeper in a caller.
"""
from dataclasses import (
dataclass as stdlib_dataclass,
field,
)
from datetime import date, datetime
from enum import Enum
from typing import TYPE_CHECKING, Any, Literal, TypedDict
from uuid import UUID
from pydantic.dataclasses import dataclass
from posthog.dataclasses import frozen
if TYPE_CHECKING:
from posthog.schema import PersonPropertyFilter
class AccountPersonsPropertyAccessError(Exception):
pass
@frozen
class AccountPersonsOptions:
limit: int
offset: int
search: str
properties: list[str]
filters: list["PersonPropertyFilter"]
sort_column: str
sort_direction: Literal["asc", "desc"]
@frozen
class AccountPerson:
id: str
display_name: str
distinct_ids: list[str]
properties: dict[str, object]
account_first_seen: datetime
account_last_seen: datetime
@frozen
class AccountPersonsPage:
results: list[AccountPerson]
columns: list[str]
limit: int
offset: int
has_more: bool
next_offset: int | None
class InvalidCustomPropertyOptions(ValueError):
"""Raised when a select property's options fail validation; the viewset maps it to a 400."""
class EventStreamTestMessageError(Exception):
"""The test message could not be sent — unconfigured stream or a Slack API failure."""
@dataclass(frozen=True)
class AccountAssignment:
"""A user assigned to an account relationship (CSM, account executive, ...)."""
id: int
email: str
@stdlib_dataclass(frozen=True)
class AccountRelationshipDefinition:
"""A team-defined account relationship type (CSM, Onboarding manager, ...).
Stdlib dataclass with defaults so the wrapping ``DataclassSerializer`` can construct it
from partial request bodies (see :class:`CustomPropertyDefinitionView`).
"""
id: UUID | None = None
name: str = ""
description: str | None = None
is_single_holder: bool = True
is_controlled: bool = False
PinnedAccountPropertyKind = Literal["custom_property", "relationship", "account_field"]
@dataclass(frozen=True)
class PinnedAccountProperty:
kind: PinnedAccountPropertyKind
# A definition UUID for custom properties and relationships, or a field name for account fields.
id: str
class InvalidPinnedAccountProperties(ValueError):
def __init__(self, errors: list[str]) -> None:
super().__init__("; ".join(errors))
self.errors = errors
TASK_DIGEST_SEND_TIME_FORMAT = "%H:%M"
@dataclass(frozen=True)
class TaskDigestPreferences:
"""One user's task digest email preferences for one project.
``send_time`` is HH:MM in the project timezone.
"""
enabled: bool = False
send_time: str = "09:00"
cadence: Literal["weekdays", "every_day"] = "weekdays"
@dataclass(frozen=True)
class AccountDetailTabsConfig:
ordered_tab_ids: list[str] = field(default_factory=list)
hidden_tab_ids: list[str] = field(default_factory=list)
default_tab_id: str | None = None
@dataclass(frozen=True)
class UserCustomerAnalyticsConfig:
pinned_properties: list[PinnedAccountProperty] = field(default_factory=list)
task_digest: TaskDigestPreferences = field(default_factory=TaskDigestPreferences)
account_detail_tabs: AccountDetailTabsConfig = field(default_factory=AccountDetailTabsConfig)
RelationshipSourceValue = Literal["human", "workflow", "ai", "salesforce_claim", "migration"]
@dataclass(frozen=True)
class AccountRelationship:
"""One assignment of a user to an account relationship, with its effective range and which kind
of writer started it (None on rows written before provenance was recorded)."""
id: UUID
definition: AccountRelationshipDefinition
user: AccountAssignment | None
started_at: datetime
ended_at: datetime | None
source: RelationshipSourceValue | None = None
@dataclass(frozen=True)
class AccountProperties:
"""Typed account properties — external-system identifiers.
Mirrors ``models.account.AccountProperties`` as a stable, framework-free shape.
"""
website_domain: str | None = None
stripe_customer_id: str | None = None
hubspot_deal_id: str | None = None
billing_id: str | None = None
sfdc_id: str | None = None
zendesk_id: str | None = None
slack_channel_id: str | None = None
usage_dashboard_link: str | None = None
metabase_link: str | None = None
@dataclass(frozen=True)
class Account:
"""A customer-analytics account."""
id: UUID
team_id: int
external_id: str | None
name: str
properties: AccountProperties
created_at: datetime | None
@dataclass(frozen=True)
class AccountPresenceViewer:
user_id: int
display_name: str
@dataclass(frozen=True)
class AccountPresence:
account_id: UUID
viewers: list[AccountPresenceViewer]
@dataclass(frozen=True)
class EmailAccountMatch:
account_id: str
account_external_id: str | None
match_source: str
@dataclass(frozen=True)
class AccountDueForSlackSummary:
"""An account whose bound Slack channel is due a periodic summary.
``period_start``/``period_end`` are the UTC instants of the last closed calendar
window (yesterday, last ISO week, last month) in the account team's timezone.
"""
team_id: int
account_id: str
account_name: str
slack_channel_id: str
cadence: str
period_start: datetime
period_end: datetime
@dataclass(frozen=True)
class AccountSlackSummaryBinding:
"""An account's current summary opt-in: its cadence and bound Slack channel."""
cadence: str
slack_channel_id: str
@dataclass(frozen=True)
class AccountChannelSummaryView:
"""A stored channel summary as returned by the account summaries endpoint."""
id: UUID
slack_channel_id: str
cadence: str
period_start: datetime
period_end: datetime
content: str
message_count: int
# [{author, sent_at, permalink}] per covered message — metadata only, never text.
messages: list[dict]
generated_at: datetime
@dataclass(frozen=True)
class CalendarSyncStatus:
"""Sync state of one connected calendar, as shown in settings."""
integration_id: int
last_synced_at: datetime | None
is_syncing: bool
sync_interval_minutes: int
@dataclass(frozen=True)
class MeetingParticipantView:
"""One attendee of a synced calendar meeting."""
email: str
display_name: str
response_status: str
is_organizer: bool
person_id: UUID | None
@dataclass(frozen=True)
class MeetingView:
"""A synced calendar meeting as returned by the account meetings endpoint."""
id: UUID
title: str
is_recurring: bool
gong_url: str | None
start_time: datetime
end_time: datetime | None
organizer_email: str
status: str
participants: list[MeetingParticipantView]
@dataclass(frozen=True)
class AccountRef:
"""Lightweight account reference for search/list result rows.
``id`` is the stringified UUID — entity-search rows are emitted as plain dicts
keyed by string ids.
"""
id: str
name: str
external_id: str | None
class AccountTableField(str, Enum):
NAME = "name"
EXTERNAL_ID = "external_id"
CREATED_AT = "created_at"
UPDATED_AT = "updated_at"
CHURNED_AT = "churned_at"
IGNORED_AT = "ignored_at"
STRIPE_CUSTOMER_ID = "stripe_customer_id"
HUBSPOT_DEAL_ID = "hubspot_deal_id"
BILLING_ID = "billing_id"
SFDC_ID = "sfdc_id"
ZENDESK_ID = "zendesk_id"
@dataclass(frozen=True, kw_only=True)
class AccountTableColumnSelection:
use_default_columns: bool = False
account_fields: frozenset[AccountTableField] = frozenset()
include_tags: bool = False
include_note_count: bool = False
relationship_definition_ids: frozenset[UUID] = frozenset()
custom_property_definition_ids: frozenset[UUID] = frozenset()
custom_property_history_windows: dict[UUID, int] = field(default_factory=dict)
@dataclass(frozen=True, kw_only=True)
class AccountTableSearchFilter:
query: str
@dataclass(frozen=True, kw_only=True)
class AccountTableTagsFilter:
tag_names: tuple[str, ...]
@dataclass(frozen=True, kw_only=True)
class AccountTableAssignedToFilter:
user_ids: tuple[int, ...]
@dataclass(frozen=True, kw_only=True)
class AccountTableAssignedFilter:
pass
@dataclass(frozen=True, kw_only=True)
class AccountTableUnassignedFilter:
pass
class AccountTableRelationshipOperator(str, Enum):
EXACT = "exact"
IS_NOT = "is_not"
IS_SET = "is_set"
IS_NOT_SET = "is_not_set"
@dataclass(frozen=True, kw_only=True)
class AccountTableRelationshipFilter:
definition_id: UUID
operator: AccountTableRelationshipOperator
user_ids: tuple[int, ...] = ()
@dataclass(frozen=True, kw_only=True)
class AccountTableAccountIdFilter:
account_id: UUID
class AccountTableFieldOperator(str, Enum):
EXACT = "exact"
IS_NOT = "is_not"
CONTAINS = "icontains"
DOES_NOT_CONTAIN = "not_icontains"
IS_SET = "is_set"
IS_NOT_SET = "is_not_set"
DATE_EXACT = "is_date_exact"
DATE_BEFORE = "is_date_before"
DATE_AFTER = "is_date_after"
@dataclass(frozen=True, kw_only=True)
class AccountTableFieldFilter:
field: AccountTableField
operator: AccountTableFieldOperator
values: tuple[str, ...] = ()
class AccountTableCustomPropertyOperator(str, Enum):
EXACT = "exact"
IS_NOT = "is_not"
CONTAINS = "icontains"
DOES_NOT_CONTAIN = "not_icontains"
REGEX = "regex"
NOT_REGEX = "not_regex"
GREATER_THAN = "gt"
GREATER_THAN_OR_EQUAL = "gte"
LESS_THAN = "lt"
LESS_THAN_OR_EQUAL = "lte"
IS_SET = "is_set"
IS_NOT_SET = "is_not_set"
DATE_EXACT = "is_date_exact"
DATE_BEFORE = "is_date_before"
DATE_AFTER = "is_date_after"
@dataclass(frozen=True, kw_only=True)
class AccountTableCustomPropertyFilter:
definition_id: UUID
operator: AccountTableCustomPropertyOperator
values: tuple[float | bool | str, ...] = ()
AccountTableFilter = (
AccountTableSearchFilter
| AccountTableTagsFilter
| AccountTableAssignedToFilter
| AccountTableAssignedFilter
| AccountTableUnassignedFilter
| AccountTableRelationshipFilter
| AccountTableAccountIdFilter
| AccountTableFieldFilter
| AccountTableCustomPropertyFilter
)
class AccountTrackRuleFieldKind(str, Enum):
ACCOUNT_FIELD = "account_field"
CUSTOM_PROPERTY = "custom_property"
@dataclass(frozen=True, kw_only=True)
class AccountTrackRuleField:
kind: AccountTrackRuleFieldKind
field: AccountTableField | None = None
definition_id: UUID | None = None
@dataclass(frozen=True, kw_only=True)
class AccountTrackRuleCondition:
field: AccountTrackRuleField
operator: str
values: tuple[float | bool | str, ...] = ()
@dataclass(frozen=True, kw_only=True)
class AccountTrackRuleGroup:
conditions: tuple[AccountTrackRuleCondition, ...]
@dataclass(frozen=True, kw_only=True)
class AccountTrackRulesConfig:
schema_version: int = 1
version: int = 0
enabled: bool = False
groups: tuple[AccountTrackRuleGroup, ...] = ()
@dataclass(frozen=True, kw_only=True)
class AccountTrackRuleSample:
id: UUID
name: str
external_id: str | None
rule_values: dict[str, float | bool | str | None]
@dataclass(frozen=True, kw_only=True)
class AccountTrackRulePreview:
config_version: int
eligible_active: int
skipped_churned: int
tracked: int
ignored: int
newly_ignored: int
restored: int
tracked_samples: tuple[AccountTrackRuleSample, ...]
ignored_samples: tuple[AccountTrackRuleSample, ...]
validation_errors: tuple[str, ...] = ()
@dataclass(frozen=True, kw_only=True)
class AccountTrackRuleRunView:
id: UUID
config_version: int
trigger: str
status: str
eligible_active: int
skipped_churned: int
tracked: int
ignored: int
newly_ignored: int
restored: int
started_at: datetime | None
finished_at: datetime | None
error: str | None
created_by: int | None
created_at: datetime
class AccountTableSortKind(str, Enum):
ACCOUNT_FIELD = "account_field"
TAGS = "tags"
NOTE_COUNT = "note_count"
RELATIONSHIP = "relationship"
CUSTOM_PROPERTY = "custom_property"
class AccountTableSortDirection(str, Enum):
ASCENDING = "asc"
DESCENDING = "desc"
@dataclass(frozen=True, kw_only=True)
class AccountTableSort:
kind: AccountTableSortKind
direction: AccountTableSortDirection
account_field: AccountTableField | None = None
definition_id: UUID | None = None
class AccountTableAggregation(str, Enum):
SUM = "sum"
AVERAGE = "avg"
MINIMUM = "min"
MAXIMUM = "max"
MEDIAN = "median"
class AccountTableThresholdOperator(str, Enum):
GREATER_THAN = "gt"
GREATER_THAN_OR_EQUAL = "gte"
LESS_THAN = "lt"
LESS_THAN_OR_EQUAL = "lte"
EQUAL = "exact"
NOT_EQUAL = "is_not"
@dataclass(frozen=True, kw_only=True)
class AccountTableCountMetric:
pass
@dataclass(frozen=True, kw_only=True)
class AccountTableAggregateMetric:
aggregation: AccountTableAggregation
definition_id: UUID
scale: float | None = None
@dataclass(frozen=True, kw_only=True)
class AccountTableCountThresholdMetric:
definition_id: UUID
operator: AccountTableThresholdOperator
value: float
AccountTableMetric = AccountTableCountMetric | AccountTableAggregateMetric | AccountTableCountThresholdMetric
@dataclass(frozen=True, kw_only=True)
class AccountTableCustomPropertyHistoryPoint:
timestamp: datetime
value: float
@dataclass(frozen=True, kw_only=True)
class AccountTableRow:
id: UUID
name: str
external_id: str | None
logo_domain: str | None = None
account_fields: dict[AccountTableField, str | None] = field(default_factory=dict)
tags: list[str] | None = None
note_count: int | None = None
relationships: dict[UUID, list[int]] = field(default_factory=dict)
custom_properties: dict[UUID, float | bool | str | None] = field(default_factory=dict)
custom_property_history: dict[UUID, list[AccountTableCustomPropertyHistoryPoint]] = field(default_factory=dict)
@dataclass(frozen=True, kw_only=True)
class AccountTableCustomPropertyDefinition:
id: UUID
name: str
description: str | None
display_type: str
is_big_number: bool
is_canonical: bool
has_workflow_reference: bool
source_id: UUID | None
options: list[dict[str, str]] | None
@dataclass(frozen=True, kw_only=True)
class AccountTablePage:
relationship_definitions: list[AccountRelationshipDefinition] = field(default_factory=list)
custom_property_definitions: list[AccountTableCustomPropertyDefinition] = field(default_factory=list)
rows: list[AccountTableRow]
has_more: bool
limit: int
offset: int
@dataclass(frozen=True)
class AccountNote:
"""An internal note (notebook) attached to an account."""
title: str | None
short_id: str
@dataclass(frozen=True)
class AccountContextData:
"""The account fields plus cross-cutting reads (tags, internal notes) the
assistant's account-context formatter renders for one account.
The configured group-type index stays with the consumer — it reads the core
``Team.customer_analytics_config`` property, not product internals.
"""
id: UUID
name: str
external_id: str | None
created_at: datetime | None
churned_at: datetime | None
ignored_at: datetime | None
properties: AccountProperties
tags: list[str] = field(default_factory=list)
notes: list[AccountNote] = field(default_factory=list)
relationships: list[AccountRelationship] = field(default_factory=list)
@dataclass(frozen=True)
class ExternalAccount:
"""The account shape the external (CDP worker) API serializes verbatim.
``properties`` is carried as a plain dict set to exactly
``account.properties.model_dump(mode="json")`` — a validated pydantic
pass-through, not a re-typed projection. ``id`` is the stringified UUID,
while ``churned_at`` and ``ignored_at`` carry lifecycle timestamps.
``custom_properties`` contains every team-defined custom property definition
keyed by definition name, with the account's current scalar value (or ``None``
when unset). Every definition is present so result paths are deterministic even
when a property hasn't been set on this account yet.
"""
id: str
external_id: str | None
name: str
churned_at: datetime | None
ignored_at: datetime | None
properties: dict
ownership: "ExternalAccountOwnership"
tags: list[str] = field(default_factory=list)
relationships: dict[str, list[dict]] = field(default_factory=dict)
custom_properties: dict[str, float | bool | str | None] = field(default_factory=dict)
@dataclass(frozen=True)
class ExternalAccountOwnershipHolder:
"""The user holding a controlled relationship, with the checks a consumer needs before projecting them."""
user_id: int
email: str | None
name: str | None
is_organization_member: bool
is_active: bool
OwnershipRoleStateValue = Literal["unmanaged", "assigned", "cleared", "blocked"]
OwnershipRoleDiagnosticValue = Literal[
"holder_missing",
"holder_inactive",
"holder_not_in_organization",
"multiple_active_holders",
]
@dataclass(frozen=True)
class ExternalAccountRoleOwnership:
"""One controlled relationship on one account.
``state`` is what the consumer may act on: ``unmanaged`` keeps legacy authority whatever the
rows say, ``assigned`` and ``cleared`` are authoritative, and ``blocked`` means the holder
cannot be projected and the consumer keeps its last applied value. ``diagnostics`` explain a
block and are informational on an unmanaged role.
"""
definition_id: UUID
definition_name: str
state: OwnershipRoleStateValue
controlled_at: datetime | None
relationship_id: UUID | None
holder: ExternalAccountOwnershipHolder | None
diagnostics: list[OwnershipRoleDiagnosticValue] = field(default_factory=list)
@dataclass(frozen=True)
class ExternalAccountOwnership:
"""Canonical identity plus every controlled relationship of the team, on the external wire
shape. Consumers map ``definition_id`` to the roles they project."""
account_id: str
external_id: str | None
region: str | None
roles: list[ExternalAccountRoleOwnership]
OwnershipClaimOutcome = Literal["accepted", "already_applied", "cleared", "not_held", "rejected", "blocked"]
OwnershipClaimReason = Literal[
"account_not_found",
"binding_changed",
"identity_mismatch",
"assignee_not_member",
"role_occupied",
"stale_allocation",
"future_allocation",
]
@dataclass(frozen=True)
class OwnershipClaimDecision:
"""An eligible initial allocation as frozen on a Salesforce Task, read from the warehouse.
The Task id (``source_ref``) is the idempotency key. A Task that has since been disqualified
carries ``released_at`` and who released it; that row withdraws the same Task's claim.
"""
source_ref: str
organization_id: str
region: str
assignee_user_id: int
source_assignee_id: str
allocated_at: datetime
released_at: datetime | None = None
source_releaser_id: str | None = None
@property
def is_release(self) -> bool:
return self.released_at is not None
@dataclass(frozen=True)
class OwnershipClaimResult:
"""What customer analytics did with a decision. ``rejected`` and ``blocked`` carry a reason;
``blocked`` means the decision may apply after review, ``rejected`` that it does not apply as
read. Refusals are not stored, so every sweep evaluates the Task again, and a refusal turns into an
acceptance once its cause is gone."""
outcome: OwnershipClaimOutcome
reason: OwnershipClaimReason | None
relationship_id: UUID | None
controlled_at: datetime | None
@dataclass(frozen=True)
class ExternalAccountAssignment:
"""An active relationship assignment on the external list wire shape.
Carries the assigned user's id and current email plus their display name so
external consumers (the billing service's ownership sync) don't need a
second lookup. ``name`` is None when the user has no name set.
"""
user_id: int
email: str
name: str | None = None
@dataclass(frozen=True)
class ExternalAccountListItem:
"""One account row on the external list wire shape, with its churn timestamp and
active relationship assignments to current organization members keyed by definition name."""
external_id: str
name: str
churned_at: datetime | None
ignored_at: datetime | None
ownership: ExternalAccountOwnership
relationships: dict[str, list[ExternalAccountAssignment]] = field(default_factory=dict)
@dataclass(frozen=True)
class ExternalAccountListPage:
"""A page of external account rows. ``next_cursor`` is the last account id
of a full page, or None when the listing is exhausted."""
results: list[ExternalAccountListItem] = field(default_factory=list)
next_cursor: str | None = None
class ExternalAccountUpdateError(Enum):
"""Failure modes of the external account write, each mapping to a distinct
HTTP response in the view."""
NOT_FOUND = "not_found"
USER_NOT_IN_ORGANIZATION = "user_not_in_organization"
RELATIONSHIP_DEFINITION_NOT_FOUND = "relationship_definition_not_found"
ROLE_MANAGED = "role_managed"
INVALID_PROPERTIES = "invalid_properties"
UPDATE_FAILED = "update_failed"
@dataclass(frozen=True)
class ExternalAccountUpdateResult:
"""Outcome of the external account write, modeled so the view can map each
case to its exact HTTP status and error string without holding write logic.
Exactly one of ``account`` / ``error`` is set. ``error_field`` carries the
role field name for a ``USER_NOT_IN_ORGANIZATION`` failure (so the view can
keep the ``"{field}: ..."`` message shape); it is None otherwise.
"""
account: ExternalAccount | None = None
error: ExternalAccountUpdateError | None = None
error_field: str | None = None
# --- Presentation wave: views that back the Accounts CRUD endpoints ---
#
# These contracts shape the DRF responses for the account/customer-journey/
# customer-profile-config viewsets. They are wire-faithful to the pre-isolation
# ``ModelSerializer`` output so the OpenAPI schema (and every downstream generated
# type / MCP tool) stays byte-identical. ``Any`` is used for free-form JSON values
# (account properties, notebook content) so pydantic passes them through verbatim
# rather than coercing.
@stdlib_dataclass(frozen=True)
class UserBasicInfo:
"""Mirror of ``posthog.api.shared.UserBasicSerializer`` output, field-for-field.
Carries the raw user values (not the rendered representation) so the presentation
layer can serialize it through the core ``UserBasicSerializer`` — keeping the
generated ``UserBasic`` OpenAPI component identical. ``hedgehog_config`` stays the
raw stored value; ``UserBasicSerializer.get_hedgehog_config`` shapes it at render
time exactly as before.
"""
id: int
uuid: UUID
distinct_id: str | None
first_name: str
last_name: str
email: str
is_email_verified: bool | None
hedgehog_config: Any
role_at_organization: str | None
@stdlib_dataclass(frozen=True)
class AccountDetails:
"""An account as returned by the accounts list/detail endpoints.
``properties`` is the raw stored JSON dict (``Account._properties``), not the
typed :class:`AccountProperties`, so ``exclude_unset`` semantics are preserved —
an account with no assignments serializes ``properties`` as ``{}`` rather than a
full object of nulls. ``created_by`` is the creator's user id (or ``None``),
matching the model serializer's ``PrimaryKeyRelatedField`` output.
The serializer that wraps this contract is reused as the viewset's
``serializer_class`` for both request and response (keeping the OpenAPI ``Account``
/ ``PatchedAccount`` components byte-identical to the old ``ModelSerializer``). To
let that serializer instantiate the contract from a partial PATCH body, every field
carries a default — those defaults never reach output (the facade always supplies
real values) and never relax validation (the serializer pins ``required`` /
``read_only`` explicitly).
"""
id: UUID | None = None
name: str = ""
external_id: str | None = None
properties: dict = field(default_factory=dict)
tags: list[str] = field(default_factory=list)
notebooks: list[str] = field(default_factory=list)
slack_summary_cadence: str | None = None
churned_at: datetime | None = None
ignored_at: datetime | None = None
created_at: datetime | None = None
created_by: int | None = None
updated_at: datetime | None = None
@dataclass(frozen=True)
class AccountView:
id: UUID
name: str
visibility: Literal["private", "team"]
content: dict[str, Any]
text_content: str
version: int
created_by: int | None
last_modified_by: int | None
created_at: datetime
updated_at: datetime
can_edit: bool
can_delete: bool
can_change_visibility: bool
@stdlib_dataclass(frozen=True)
class CustomerJourneyView:
"""A customer journey as returned by the customer-journey endpoints.
Defaults exist for the same reason as :class:`AccountDetails` — the wrapping serializer
doubles as request + response so the OpenAPI components stay identical.
"""
id: UUID | None = None
insight: int = 0
name: str = ""
description: str | None = None
created_at: datetime | None = None
created_by: int | None = None
updated_at: datetime | None = None
@stdlib_dataclass(frozen=True)
class FeatureRequestProductAreaView:
id: UUID | None = None
name: str = ""
display_order: int = 0
is_active: bool = True
created_at: datetime | None = None
updated_at: datetime | None = None
@stdlib_dataclass(frozen=True)
class FeatureRequestAccountView:
id: UUID | None = None
name: str = ""
@stdlib_dataclass(frozen=True)
class FeatureRequestEvidenceView:
id: UUID | None = None
summary: str = ""
customer_quote: str = ""
evidence_source: str = "conversation"
source_url: str = ""
requested_on: date | None = None
image_ids: list[UUID] = field(default_factory=list)
created_by: int | None = None
updated_by: int | None = None
created_at: datetime | None = None
updated_at: datetime | None = None
@stdlib_dataclass(frozen=True)
class FeatureRequestAccountLinkView:
id: UUID | None = None
account: FeatureRequestAccountView | None = None
evidence: list[FeatureRequestEvidenceView] = field(default_factory=list)
evidence_count: int = 0
created_at: datetime | None = None
updated_at: datetime | None = None
@stdlib_dataclass(frozen=True)
class FeatureRequestGitHubLinkView:
id: UUID | None = None
issue_url: str = ""
repository: str = ""
issue_number: int = 0
issue_title: str = ""
issue_state: Literal["open", "closed"] = "open"
sync_enabled: bool = True
last_synced_at: datetime | None = None
@stdlib_dataclass(frozen=True)
class FeatureRequestView:
id: UUID | None = None
title: str = ""
description: str = ""
request_status: str = "requested"
request_priority: str | None = None
is_archived: bool = False
archived_at: datetime | None = None
archived_by: int | None = None
version: int = 1
can_update: bool = False
account: FeatureRequestAccountView | None = None
account_links: list[FeatureRequestAccountLinkView] = field(default_factory=list)
evidence_count: int = 0
product_areas: list[FeatureRequestProductAreaView] = field(default_factory=list)
github_link: FeatureRequestGitHubLinkView | None = None
created_by: int | None = None
updated_by: int | None = None
created_at: datetime | None = None
updated_at: datetime | None = None
class FeatureRequestHistoryChange(TypedDict):
field: str
before: object
after: object
@dataclass(frozen=True)
class FeatureRequestHistoryView:
id: UUID
changes: list[FeatureRequestHistoryChange]
is_initial: bool
change_source: str
actor_id: int | None
actor_name: str | None
changed_at: datetime
@dataclass(frozen=True)
class FeatureRequestStatusHistoryView:
id: UUID
previous_status: str | None
request_status: str
change_source: str
actor_id: int | None
actor_name: str | None
changed_at: datetime
@dataclass(frozen=True)
class FeatureRequestListFilters:
search: str = ""
statuses: tuple[str, ...] = ()
priorities: tuple[str, ...] = ()
product_area_ids: tuple[UUID, ...] = ()
account_ids: tuple[UUID, ...] = ()
created_by_ids: tuple[int, ...] = ()
archive_state: str = "active"
ordering: str = "-updated_at"
@dataclass(frozen=True)
class FeatureRequestEvidenceInput:
summary: str
customer_quote: str
evidence_source: str
source_url: str
requested_on: date | None
image_ids: tuple[UUID, ...] = ()
@dataclass(frozen=True)
class CreateFeatureRequestInput:
title: str
description: str
account_id: UUID
product_area_ids: tuple[UUID, ...]
idempotency_key: UUID
evidence: FeatureRequestEvidenceInput | None = None
@dataclass(frozen=True)
class FeatureRequestCreateOutcome:
request: FeatureRequestView
created: bool
@dataclass(frozen=True)
class UpdateFeatureRequestInput:
expected_version: int
title: str | None = None
description: str | None = None
account_ids: tuple[UUID, ...] | None = None
product_area_ids: tuple[UUID, ...] | None = None
request_status: str | None = None
request_priority: str | None = None
request_priority_is_set: bool = False
@dataclass(frozen=True)
class LinkFeatureRequestGitHubInput:
expected_version: int
integration_id: int
issue_url: str
@dataclass(frozen=True)
class AddFeatureRequestAccountInput:
expected_version: int
account_id: UUID
evidence: FeatureRequestEvidenceInput | None = None
@dataclass(frozen=True)
class CreateFeatureRequestEvidenceInput:
expected_version: int
account_link_id: UUID
summary: str
customer_quote: str
evidence_source: str
source_url: str
requested_on: date | None
image_ids: tuple[UUID, ...] = ()
@dataclass(frozen=True)
class UpdateFeatureRequestEvidenceInput:
expected_version: int
evidence_id: UUID
summary: str
customer_quote: str
evidence_source: str
source_url: str
requested_on: date | None
image_ids: tuple[UUID, ...] | None = None
@dataclass(frozen=True)
class DeleteFeatureRequestEvidenceInput:
expected_version: int
evidence_id: UUID
@stdlib_dataclass(frozen=True)
class CustomerProfileConfigView:
"""A customer profile config as returned by the profile-config endpoints.
Defaults exist so the wrapping serializer can parse partial request bodies (see
:class:`AccountDetails`).
"""
id: UUID | None = None
scope: str = ""
content: Any = None
sidebar: Any = None
created_at: datetime | None = None
updated_at: datetime | None = None
@stdlib_dataclass(frozen=True)
class CustomPropertyReference:
"""A place that uses a custom property definition. ``type`` discriminates the kind of
referrer (``workflow`` for now); ``id``/``name``/``status`` identify the referring entity."""
id: str
name: str
status: str
type: str = "workflow"
@stdlib_dataclass(frozen=True)
class CustomPropertyOption:
"""One allowed value of a select custom property. ``id`` is server-assigned and stable across
renames so option edits can be diffed; ``color`` is a preset data-color token."""
label: str = ""
color: str = ""
id: str | None = None
@stdlib_dataclass(frozen=True)
class CustomPropertyDefinitionView:
"""A team-scoped custom account-property definition as returned by the
custom-property-definitions endpoints.
Defaults exist so the wrapping serializer can parse partial request bodies (see
:class:`AccountDetails`). ``created_by`` is the creator's user id (or ``None``), matching
the old model serializer's ``PrimaryKeyRelatedField`` output. ``references`` lists where the
property is used (workflows), resolved by definition id. ``source`` is the read-only
view-sync binding when one is configured for this definition, else ``None``.
"""
id: UUID | None = None
name: str = ""
description: str | None = None
display_type: str = "text"
target_type: str = "account"
# Only set for group targets: which group type (0-4) the property attaches to. Null otherwise.
group_type_index: int | None = None
is_big_number: bool = False
is_canonical: bool = False
created_at: datetime | None = None
created_by: int | None = None
updated_at: datetime | None = None
references: list[CustomPropertyReference] = field(default_factory=list)
has_workflow_reference: bool = False
source: "CustomPropertySourceView | None" = None
options: list[CustomPropertyOption] | None = None
@stdlib_dataclass(frozen=True)
class CustomPropertySourceView:
"""A custom-property source: binds warehouse columns to a definition, feeding its values on every
warehouse run of what it reads.
``definition`` / ``saved_query`` / ``external_data_schema`` are ids (the definition this feeds, and
the warehouse object read from). ``last_sync_error`` is null when the last run succeeded or hasn't
run. Account-target sources set ``saved_query`` + ``source_column``; person- and group-target
sources set ``column_property_map`` plus exactly one of ``external_data_schema`` (an imported
table) and ``saved_query`` (a materialized view). Defaults exist so the wrapping serializer can
parse partial request bodies (see :class:`AccountDetails`).
"""
id: UUID | None = None
definition: UUID | None = None
saved_query: UUID | None = None
external_data_schema: UUID | None = None
source_column: str | None = ""
key_column: str = ""
column_property_map: dict | None = None
column_descriptions: dict | None = None
is_enabled: bool = True
consecutive_failures: int = 0
last_synced_at: datetime | None = None
last_sync_error: str | None = None
created_at: datetime | None = None
created_by: int | None = None
updated_at: datetime | None = None
# Person/group-target schedule visibility (None for account sources). ``sync_frequency_interval``
# is in seconds; ``next_sync_at`` is approximate (last run + interval), it drifts if the underlying
# schedule was paused, and is null for a view whose frequency lives on its DAG node.
# ``latest_run`` is the most recent sync/backfill run.
sync_frequency_interval_seconds: float | None = None
next_sync_at: datetime | None = None
latest_run: "CustomPropertySyncRunView | None" = None
# Person/group-target warehouse binding, for naming and linking to what this source reads.
# ``table_name`` is the imported table as named in HogQL, or the view's name. ``external_data_source``
# is the warehouse source owning the schema, set only for a table binding; ``saved_query_name`` is
# set only for a view binding. All None for account sources.
external_data_source: UUID | None = None
table_name: str | None = None
saved_query_name: str | None = None
@stdlib_dataclass(frozen=True)
class CustomPropertySyncRunView:
"""One warehouse-backed custom property sync run."""
id: UUID | None = None
job_id: str | None = None
account_segment: str | None = None
sync_phase: str | None = None
attempt: int | None = None
workflow_id: str | None = None
workflow_run_id: UUID | None = None
temporal_url: str | None = None
trigger: str = ""
status: str = ""
started_at: datetime | None = None
finished_at: datetime | None = None
rows_read: int = 0
changed: int = 0
existing: int = 0
produced: int = 0
skipped_missing_person: int = 0
error: str | None = None
created_at: datetime | None = None
@stdlib_dataclass(frozen=True)
class AccountNotebookView:
"""An account notebook as returned by the nested account-notebooks endpoints.
Defaults exist so the wrapping serializer can parse partial request bodies (see
:class:`AccountDetails`).
"""
id: UUID | None = None
short_id: str = ""
title: str | None = None
content: Any = None
text_content: str | None = None
created_at: datetime | None = None
created_by: UserBasicInfo | None = None
last_modified_at: datetime | None = None
last_modified_by: UserBasicInfo | None = None
@dataclass(frozen=True)
class AccountNoteView:
"""A row of the team-wide account-notes list: an internal notebook plus the account it's
linked to. Read-only (the wrapping serializer never parses request bodies), so fields are
strict — no serializer-instantiation defaults like :class:`AccountDetails` needs."""
short_id: str
title: str | None
created_at: datetime
last_modified_at: datetime
account_id: UUID
account_name: str
created_by: UserBasicInfo | None = None
# --- Presentation wave: input contracts for the CRUD write paths ---
@dataclass(frozen=True)
class CreateAccountInput:
"""Validated body for creating an account.
``properties`` is the raw client dict; the facade hands it to the model manager,
which validates it against the pydantic ``AccountProperties`` schema (rejecting
unknown keys and malformed assignments).
"""
name: str
external_id: str | None = None
properties: dict = field(default_factory=dict)
tags: list[str] | None = None
slack_summary_cadence: str | None = None
churned_at: datetime | None = None
ignored_at: datetime | None = None
@dataclass(frozen=True)
class UpdateAccountInput:
"""Validated partial body for updating an account.
Each field is optional; only the keys the caller supplied are applied, so a PATCH
that omits ``name`` leaves the name unchanged. ``tags`` of ``None`` means "tags
not provided" (left untouched), distinct from ``[]`` (clear all tags).
"""
name: str | None = None
external_id: str | None = None
properties: dict | None = None
tags: list[str] | None = None
slack_summary_cadence: str | None = None
churned_at: datetime | None = None
ignored_at: datetime | None = None
# Distinguishes omitted fields from fields explicitly set to null.
external_id_provided: bool = False
properties_provided: bool = False
slack_summary_cadence_provided: bool = False
churned_at_provided: bool = False
ignored_at_provided: bool = False
@dataclass(frozen=True)
class CreateAccountNotebookInput:
"""Validated body for creating an account notebook.
``content`` is the ProseMirror document the caller supplied (or ``None``);
``synthesized_content`` is the markdown notebook document the view built when the
caller passed only ``text_content``.
"""
title: str | None
content: Any
text_content: str | None
synthesized_content: Any = None
@dataclass(frozen=True)
class CustomPropertyValue:
"""An account's value for a custom property."""
id: UUID
account_id: UUID
definition_id: UUID
value: float | bool | str | datetime | None
created_at: datetime
created_by_id: int | None
class ExternalAccountCustomPropertiesError(Enum):
"""Failure modes of the external custom-property write, each mapping to a distinct
HTTP response in the view."""
ACCOUNT_NOT_FOUND = "account_not_found"
DEFINITION_NOT_FOUND = "definition_not_found"
INVALID_VALUE = "invalid_value"
CONFLICT = "conflict"
UPDATE_FAILED = "update_failed"
SOURCE_MANAGED = "source_managed"
@dataclass(frozen=True)
class ExternalAccountCustomPropertiesResult:
"""Outcome of the external custom-property write, modeled so the view can map each
case to its exact HTTP status and error string without holding write logic.
Exactly one of ``values`` / ``error`` is set. ``error_field`` carries the offending
property name for ``DEFINITION_NOT_FOUND`` / ``INVALID_VALUE`` / ``SOURCE_MANAGED`` failures;
it is None otherwise.
"""
values: list[CustomPropertyValue] | None = None
error: ExternalAccountCustomPropertiesError | None = None
error_field: str | None = None
@stdlib_dataclass(frozen=True)
class EventStreamView:
"""A user's event stream as returned by the event-stream endpoints.
One stream per user per team (``created_by`` is the owner): the events to watch
(``event_names``), the owner's Slack delivery target, and the member accounts
(``account_ids``) whose users' events are streamed.
Defaults exist so the wrapping serializer can parse partial request bodies (see
:class:`AccountDetails`).
"""
id: UUID | None = None
enabled: bool = False
event_names: list[str] = field(default_factory=list)
slack_integration: int | None = None
slack_channel_id: str = ""
slack_channel_name: str = ""
account_ids: list[UUID] = field(default_factory=list)
created_at: datetime | None = None
created_by: int | None = None
updated_at: datetime | None = None
class AnnouncementValidationError(ValueError):
def __init__(self, detail: str | dict[str, str]) -> None:
super().__init__(str(detail))
self.detail = detail
@stdlib_dataclass(frozen=True)
class AnnouncementChannelView:
id: str
name: str
is_member: bool
customer_name: str | None
@stdlib_dataclass(frozen=True)
class AnnouncementDeliveryView:
id: UUID | None = None
slack_channel_id: str = ""
slack_channel_name: str = ""
status: str = ""
error: str = ""
slack_message_ts: str = ""
sent_at: datetime | None = None
@stdlib_dataclass(frozen=True)
class AnnouncementView:
# Defaults let the wrapping DataclassSerializer parse create requests, which carry only
# message + channels; channels is write-only and always returned empty.
id: UUID | None = None
short_id: str = ""
message: str = ""
status: str = ""
send_as: str = "bot"
sender_display_name: str = ""
total_channels: int = 0
sent_count: int = 0
failed_count: int = 0
sent_at: datetime | None = None
created_at: datetime | None = None
created_by: UserBasicInfo | None = None
deliveries: list[AnnouncementDeliveryView] = field(default_factory=list)
channels: list[str] = field(default_factory=list)
class CustomerTaskAccountNotFound(Exception):
pass
class CustomerTaskAssigneeInvalid(Exception):
pass
class CustomerTaskAssigneeCannotViewAccount(Exception):
pass
class CustomerTaskRoleNotFound(Exception):
pass
class CustomerTaskInvalidTransition(Exception):
def __init__(self, current: str, requested: str) -> None:
self.current = current
self.requested = requested
super().__init__(current, requested)
class CustomerTaskArchived(Exception):
pass
class CustomerTaskAccessDenied(Exception):
pass
class CustomerTaskBulkUpdateConflict(Exception):
pass
@stdlib_dataclass(frozen=True)
class CustomerTaskUserView:
id: int
email: str
first_name: str
last_name: str
@stdlib_dataclass(frozen=True)
class CustomerTaskAccountView:
id: UUID
name: str
@stdlib_dataclass(frozen=True)
class CustomerTaskView:
id: UUID
account: CustomerTaskAccountView | None
name: str
description: str | None
status: str
assigned_to: CustomerTaskUserView | None
due_at: datetime | None
completed_at: datetime | None
completed_by: CustomerTaskUserView | None
created_by: CustomerTaskUserView | None
archived_at: datetime | None
created_at: datetime
updated_at: datetime
can_edit: bool
can_restore: bool
@stdlib_dataclass(frozen=True)
class CustomerTaskChange:
field: str
before: object | None
after: object | None
@stdlib_dataclass(frozen=True)
class CustomerTaskActivityView:
id: UUID
activity_type: str
changes: list[CustomerTaskChange]
actor: CustomerTaskUserView | None
created_at: datetime
@stdlib_dataclass(frozen=True)
class CustomerTaskListFilters:
search: str | None = None
account_id: UUID | None = None
assigned_to: str | None = None
assigned_role_id: UUID | None = None
statuses: tuple[str, ...] = ()
archive_state: str = "active"
due_after: datetime | None = None
due_before: datetime | None = None
has_due_at: bool | None = None
ordering: str | None = None
@stdlib_dataclass(frozen=True)
class CreateCustomerTaskInput:
account_id: UUID | None = None
name: str = ""
description: str | None = None
assigned_to_id: int | None = None
due_at: datetime | None = None
status: str = "open"
@stdlib_dataclass(frozen=True)
class UpdateCustomerTaskInput:
account_id: UUID | None = None
name: str | None = None
description: str | None = None
assigned_to_id: int | None = None
due_at: datetime | None = None
status: str | None = None
account_id_provided: bool = False
name_provided: bool = False
description_provided: bool = False
assigned_to_id_provided: bool = False
due_at_provided: bool = False
status_provided: bool = False
@dataclass(frozen=True)
class KeyMetric:
key: str
name: str
people: bool
daily: list[tuple[date, float]]
this_week: float
last_week: float
node: dict[str, Any]