Add governed contact point snapshots

2026-08-02 06:20:24 +02:00
parent 67392f620f
commit 2e78b9ae50
10 changed files with 1620 additions and 16 deletions
@@ -25,6 +25,19 @@ AddressChannelDecision = Literal[
    "returned",
    "temporarily_unavailable",
 ]
+AddressDistributionOutcome = Literal[
+    "usable",
+    "unresolved",
+    "invalid",
+    "suppressed",
+    "ambiguous",
+    "duplicate",
+    "policy_blocked",
+    "provider_unavailable",
+    "stale",
+]
+AddressContactPointFallbackRule = Literal["none", "primary", "any"]
+AddressPostalFormat = Literal["domestic", "international"]


 class ContactEmailPayload(BaseModel):
@@ -282,6 +295,125 @@ class ContactChannelRuleListResponse(BaseModel):
    rules: list[ContactChannelRuleResponse] = Field(default_factory=list)


+class AddressSourceReferencePayload(BaseModel):
+    provider: str = Field(min_length=1, max_length=120)
+    resource_type: str = Field(min_length=1, max_length=120)
+    resource_id: str = Field(min_length=1, max_length=1000)
+    revision: str | None = Field(default=None, max_length=1000)
+    fingerprint: str | None = Field(default=None, max_length=255)
+    label: str | None = Field(default=None, max_length=500)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class ContactPointResolveRequest(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    subject: AddressSourceReferencePayload
+    effective_at: datetime
+    purpose: str | None = Field(default=None, max_length=120)
+    requested_channels: list[AddressDistributionChannel] = Field(default_factory=list)
+    address_purpose: str | None = Field(default=None, max_length=80)
+    fallback_rule: AddressContactPointFallbackRule = "primary"
+    locale: str | None = Field(default=None, max_length=20)
+    postal_format: AddressPostalFormat = "domestic"
+    context: dict[str, Any] = Field(default_factory=dict)
+
+
+class ContactPointSourceRequestPayload(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    source_id: str = Field(min_length=1, max_length=1000)
+    effective_at: datetime
+    purpose: str | None = Field(default=None, max_length=120)
+    requested_channels: list[AddressDistributionChannel] = Field(default_factory=list)
+    address_purpose: str | None = Field(default=None, max_length=80)
+    fallback_rule: AddressContactPointFallbackRule = "primary"
+    locale: str | None = Field(default=None, max_length=20)
+    postal_format: AddressPostalFormat = "domestic"
+    max_items: int = Field(default=5000, ge=1, le=20000)
+    context: dict[str, Any] = Field(default_factory=dict)
+
+
+class ContactPointSourceRequestResponse(ContactPointSourceRequestPayload):
+    tenant_id: str
+
+
+class ContactPointCandidateResponse(BaseModel):
+    channel: AddressDistributionChannel
+    target: str
+    target_key: str
+    status: AddressDistributionOutcome
+    contact_point_id: str | None = None
+    address_purpose: str | None = None
+    locale: str | None = None
+    preferred: bool = False
+    preference_rank: int | None = None
+    reason_code: str | None = None
+    explanation: str | None = None
+    source: AddressSourceReferencePayload | None = None
+    source_revision: str | None = None
+    preference_revision: str | None = None
+    consent_revision: str | None = None
+    value: dict[str, Any] = Field(default_factory=dict)
+    provenance: dict[str, Any] = Field(default_factory=dict)
+
+
+class DistributionExplanationResponse(BaseModel):
+    code: str
+    message: str
+    severity: Literal["info", "warning", "error"]
+    provider: str | None = None
+    source: AddressSourceReferencePayload | None = None
+    provenance: dict[str, Any] = Field(default_factory=dict)
+
+
+class ContactPointResolutionResponse(BaseModel):
+    contract_version: str
+    subject: AddressSourceReferencePayload
+    status: AddressDistributionOutcome
+    contact_id: str | None = None
+    display_name: str | None = None
+    candidates: list[ContactPointCandidateResponse] = Field(default_factory=list)
+    excluded: list[ContactPointCandidateResponse] = Field(default_factory=list)
+    explanations: list[DistributionExplanationResponse] = Field(default_factory=list)
+    source_revision: str | None = None
+    source_fingerprint: str | None = None
+    provenance: dict[str, Any] = Field(default_factory=dict)
+
+
+class ContactPointSourcePreviewResponse(BaseModel):
+    contract_version: str
+    source: AddressSourceReferencePayload
+    request: ContactPointSourceRequestResponse
+    resolutions: list[ContactPointResolutionResponse]
+    total_count: int
+    usable_count: int
+    excluded_count: int
+    offset: int
+    limit: int
+    has_more: bool
+    source_revision: str
+    source_fingerprint: str
+    generated_at: datetime
+    provenance: dict[str, Any] = Field(default_factory=dict)
+
+
+class ContactPointSnapshotResponse(BaseModel):
+    id: str
+    tenant_id: str
+    contract_version: str
+    source: AddressSourceReferencePayload
+    request: ContactPointSourceRequestResponse
+    resolutions: list[ContactPointResolutionResponse]
+    recipient_count: int
+    excluded_count: int
+    source_revision: str
+    source_fingerprint: str
+    snapshot_hash: str
+    generated_at: datetime
+    provenance: dict[str, Any] = Field(default_factory=dict)
+
+
 class AddressLookupResponse(BaseModel):
    contacts: list[ContactResponse]