from __future__ import annotations import copy import dataclasses import json import logging from collections.abc import Callable, Sequence from typing import Any, Literal from fastapi import APIRouter, Depends, HTTPException, Query, Response, status from sqlalchemy import and_, exists, func, or_ from sqlalchemy.orm import Session from pydantic import BaseModel, Field from govoplan_campaign.backend.schemas import ( AppendSentRequest, BuildCampaignRequest, CampaignActionResponse, CampaignDeltaResponse, CampaignCreateRequest, CampaignUpdateRequest, CampaignCreateResponse, CampaignCreateMinimalRequest, CampaignShareItem, CampaignShareListResponse, CampaignShareTargetItem, CampaignShareTargetsResponse, CampaignShareUpsertRequest, CampaignOwnerUpdateRequest, CampaignAddressLookupCandidate, CampaignAddressLookupResponse, CampaignPostboxCatalogResponse, CampaignRecipientAddressSource, CampaignRecipientAddressSourcesResponse, CampaignRecipientAddressSourceSnapshotRequest, CampaignRecipientAddressSourceSnapshotResponse, CampaignRecipientSnapshotItem, RecipientImportMappingProfileListResponse, RecipientImportMappingProfilePayload, RecipientImportMappingProfileResponse, CampaignJobsResponse, CampaignJobsDeltaResponse, CampaignJobDetailResponse, CampaignJobDiagnosticsResponse, CampaignRetryJobsRequest, CampaignSendJobRequest, CampaignSendUnattemptedRequest, CampaignResolveOutcomeRequest, CampaignDeliveryOptionsResponse, CampaignListResponse, CampaignResponse, CampaignVersionDetailResponse, CampaignVersionResponse, CampaignWorkspaceDeltaResponse, CampaignWorkspaceResponse, CampaignVersionSetStepRequest, CampaignReviewStateRequest, CampaignVersionUpdateRequest, CampaignPartialValidationRequest, CampaignPartialValidationResponse, ValidateCampaignRequest, ReportEmailRequest, ReportEmailResponse, MockCampaignSendRequest, MockCampaignSendResponse, QueueCampaignRequest, QueueCampaignResponse, SendCampaignNowRequest, SendCampaignNowResponse, ) from govoplan_core.auth import ApiPrincipal, has_scope, require_any_scope, require_scope from govoplan_core.audit.logging import audit_from_principal from govoplan_core.core.access import CAPABILITY_ACCESS_DIRECTORY, AccessDirectory from govoplan_core.core.change_sequence import ( decode_sequence_watermark, encode_sequence_watermark, max_sequence_id, sequence_entries_since, sequence_watermark_is_expired, ) from govoplan_core.core.pagination import KeysetCursorError, decode_keyset_cursor, encode_keyset_cursor, keyset_query_fingerprint from govoplan_core.core.runtime import get_registry from govoplan_core.api.v1.schemas import DeltaDeletedItem from govoplan_campaign.backend.change_tracking import ( CAMPAIGNS_COLLECTION, CAMPAIGNS_MODULE_ID, CAMPAIGN_ATTEMPTS_COLLECTION, CAMPAIGN_ISSUES_COLLECTION, CAMPAIGN_JOBS_COLLECTION, CAMPAIGN_VERSIONS_COLLECTION, ) from govoplan_campaign.backend.db.models import ( Campaign, CampaignIssue, CampaignJob, CampaignShare, CampaignStatus, CampaignVersion, CampaignVersionWorkflowState, ImapAppendAttempt, JobImapStatus, JobPostboxStatus, JobQueueStatus, JobSendStatus, JobValidationStatus, RecipientImportMappingProfile, PostboxDeliveryAttempt, SendAttempt, ) from govoplan_campaign.backend.campaign.postbox_targets import ( delivery_catalog_payload, ) from govoplan_campaign.backend.integrations import ( PostboxDeliveryUnavailable, postbox_integration, ) from govoplan_core.db.session import get_session from govoplan_campaign.backend.reports.campaigns import CampaignReportError, generate_campaign_report, generate_jobs_csv from govoplan_campaign.backend.report_privacy_policy import CampaignReportPrivacyPolicyError from govoplan_campaign.backend.reports.aggregate import ( AggregateCampaignReport, AggregateCampaignReportError, AggregateReportCampaignList, aggregate_report_campaign_item, generate_aggregate_campaign_report, ) from govoplan_campaign.backend.response_security import ( public_campaign_payload, public_delivery_result_message, public_send_campaign_now_result, send_campaign_now_audit_details, ) from govoplan_campaign.backend.reports.emailing import CampaignReportEmailError, send_campaign_report_email from govoplan_campaign.backend.persistence.campaigns import ( CampaignPersistenceError, build_campaign_version, create_campaign_version_from_json, load_campaign_config_from_json, validate_campaign_version, ) from govoplan_campaign.backend.integrations import ( MailProfileError, SmtpConfigurationError, SmtpSendError, files_integration, ) from govoplan_campaign.backend.path_security import CampaignPathSecurityError, assert_server_safe_campaign_paths from govoplan_campaign.backend.campaign.loader import load_campaign_json from govoplan_campaign.backend.campaign.mail_profile_boundary import ( CAMPAIGN_MAIL_SERVER_KEYS, campaign_mail_profile_id, ) from govoplan_campaign.backend.attachments.resolver import resolve_campaign_attachments from govoplan_core.security.time import utc_now from govoplan_campaign.backend.persistence.versions import ( LockedCampaignVersionError, create_minimal_campaign, fork_campaign_version_for_edit, is_version_final_locked, is_user_locked_version, is_version_locked, get_campaign_version_for_tenant, lock_campaign_version_temporarily, permanently_lock_campaign_version, publish_campaign_version, unlock_user_locked_campaign_version, unlock_validated_campaign_version, update_campaign_version, update_campaign_review_state, validate_campaign_partial, ) from govoplan_campaign.backend.dev.mock_campaign import MockCampaignSendError, run_mock_campaign_send from govoplan_campaign.backend.sending.execution import ExecutionSnapshotError, clear_execution_snapshot from govoplan_campaign.backend.sending.jobs import ( QueueingError, SynchronousSendRejected, cancel_campaign_jobs, enqueue_pending_imap_appends, pause_campaign_jobs, queue_campaign_jobs, queue_failed_jobs_for_retry, queue_unattempted_jobs, reconcile_job_outcome, resume_campaign_jobs, send_campaign_now, send_single_campaign_job, synchronous_send_options, ) router = APIRouter(prefix="/campaigns", tags=["campaigns"]) logger = logging.getLogger(__name__) CAMPAIGN_JOBS_CURSOR_SCOPE = "campaign.jobs" CAPABILITY_ADDRESSES_LOOKUP = "addresses.lookup" CAPABILITY_ADDRESSES_RECIPIENT_SOURCE = "addresses.recipient_source" def _capability_payload(value: object) -> dict[str, Any]: if dataclasses.is_dataclass(value): return dataclasses.asdict(value) if isinstance(value, dict): return dict(value) payload: dict[str, Any] = {} for key in ( "contact_id", "address_book_id", "display_name", "email", "email_label", "organization", "role_title", "tags", "source_kind", "source_ref", "source_revision", "source_id", "source_label", "recipient_count", "generated_at", "recipients", "fields", "provenance", ): if hasattr(value, key): payload[key] = getattr(value, key) return payload def _registry_capability(name: str) -> object | None: registry = get_registry() if registry is None or not hasattr(registry, "has_capability") or not registry.has_capability(name): return None return registry.capability(name) def _access_directory() -> AccessDirectory: registry = get_registry() if registry is None or not hasattr(registry, "has_capability") or not registry.has_capability(CAPABILITY_ACCESS_DIRECTORY): raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail="Access directory capability is not configured") capability = registry.require_capability(CAPABILITY_ACCESS_DIRECTORY) if not isinstance(capability, AccessDirectory): raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail="Access directory capability is invalid") return capability def _get_campaign_for_tenant(session: Session, campaign_id: str, tenant_id: str) -> Campaign: campaign = session.get(Campaign, campaign_id) if not campaign or campaign.tenant_id != tenant_id: raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Campaign not found") return campaign def _get_version_for_tenant(session: Session, version_id: str, tenant_id: str) -> CampaignVersion: version = session.get(CampaignVersion, version_id) if not version: raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Campaign version not found") campaign = session.get(Campaign, version.campaign_id) if not campaign or campaign.tenant_id != tenant_id: raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Campaign version not found") return version def _principal_group_ids(session: Session, principal: ApiPrincipal) -> set[str]: del session return {group.id for group in _access_directory().groups_for_user(principal.user.id, tenant_id=principal.tenant_id)} def _campaign_acl_filter(session: Session, principal: ApiPrincipal): if has_scope(principal, "tenant:*"): return None group_ids = _principal_group_ids(session, principal) clauses = [Campaign.owner_user_id == principal.user.id] if group_ids: clauses.append(Campaign.owner_group_id.in_(group_ids)) share_clauses = [ and_( CampaignShare.tenant_id == Campaign.tenant_id, CampaignShare.campaign_id == Campaign.id, CampaignShare.revoked_at.is_(None), CampaignShare.target_type == "user", CampaignShare.target_id == principal.user.id, ) ] if group_ids: share_clauses.append( and_( CampaignShare.tenant_id == Campaign.tenant_id, CampaignShare.campaign_id == Campaign.id, CampaignShare.revoked_at.is_(None), CampaignShare.target_type == "group", CampaignShare.target_id.in_(group_ids), ) ) clauses.append(exists().where(or_(*share_clauses))) return or_(*clauses) def _campaign_acl_allows(session: Session, campaign: Campaign, principal: ApiPrincipal, *, write: bool = False) -> bool: if has_scope(principal, "tenant:*"): return True if campaign.owner_user_id == principal.user.id: return True group_ids = _principal_group_ids(session, principal) if campaign.owner_group_id and campaign.owner_group_id in group_ids: return True target_ids = [principal.user.id, *group_ids] if not target_ids: return False query = session.query(CampaignShare).filter( CampaignShare.tenant_id == campaign.tenant_id, CampaignShare.campaign_id == campaign.id, CampaignShare.revoked_at.is_(None), or_( CampaignShare.target_type == "user", CampaignShare.target_type == "group", ), CampaignShare.target_id.in_(target_ids), ) shares = query.all() if not shares: return False if not write: return True return any(item.permission == "write" for item in shares) def _require_campaign_acl(session: Session, campaign: Campaign, principal: ApiPrincipal, *, write: bool = False) -> None: if not _campaign_acl_allows(session, campaign, principal, write=write): raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Campaign is not shared with this principal") def _get_campaign_for_principal(session: Session, campaign_id: str, principal: ApiPrincipal, *, write: bool = False) -> Campaign: campaign = _get_campaign_for_tenant(session, campaign_id, principal.tenant_id) _require_campaign_acl(session, campaign, principal, write=write) return campaign def _require_permission(principal: ApiPrincipal, scope: str) -> None: if not has_scope(principal, scope): raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail=f"Missing scope: {scope}") def _campaign_query_for_principal(session: Session, principal: ApiPrincipal): query = session.query(Campaign).filter(Campaign.tenant_id == principal.tenant_id, Campaign.status != "deleted") acl_filter = _campaign_acl_filter(session, principal) if acl_filter is not None: query = query.filter(acl_filter) return query def _get_recipient_import_profile_for_principal(session: Session, profile_id: str, principal: ApiPrincipal) -> RecipientImportMappingProfile: profile = session.get(RecipientImportMappingProfile, profile_id) if not profile or profile.tenant_id != principal.tenant_id or profile.owner_user_id != principal.user.id: raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Recipient import mapping profile not found") return profile def _apply_recipient_import_profile_payload(profile: RecipientImportMappingProfile, payload: RecipientImportMappingProfilePayload) -> None: profile.name = payload.name.strip() profile.column_count = payload.column_count profile.headers = list(payload.headers) profile.normalized_headers = list(payload.normalized_headers) profile.ordered_header_fingerprint = payload.ordered_header_fingerprint profile.unordered_header_fingerprint = payload.unordered_header_fingerprint profile.delimiter = payload.delimiter profile.header_rows = payload.header_rows profile.quoted = payload.quoted profile.value_separators = payload.value_separators profile.mappings = [mapping.model_dump(mode="json") for mapping in payload.mappings] def _recipient_sections_changed(current: dict[str, object] | None, proposed: dict[str, object] | None) -> bool: if proposed is None: return False current = current or {} return any(current.get(key) != proposed.get(key) for key in ("recipients", "entries")) def _campaign_mail_profile_id(raw_json: dict[str, object] | None) -> str | None: return campaign_mail_profile_id(raw_json) def _require_mail_profile_use_if_needed(principal: ApiPrincipal, raw_json: dict[str, object] | None) -> None: if _campaign_mail_profile_id(raw_json) and not has_scope(principal, "mail:profile:use"): raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Missing scope: mail:profile:use") def _campaign_response_context(principal: ApiPrincipal) -> dict[str, bool]: return {"include_diagnostics": has_scope(principal, "campaigns:diagnostic:read")} def _campaign_version_detail_response( session: Session, principal: ApiPrincipal, campaign_id: str, mutation: Callable[[], CampaignVersion], *, audit_action: str, details: dict[str, Any] | Callable[[CampaignVersion], dict[str, Any]] | None = None, validation_error_status: int | None = None, ) -> CampaignVersionDetailResponse: try: version = mutation() audit_details = details(version) if callable(details) else dict(details or {"campaign_id": campaign_id}) audit_from_principal( session, principal, action=audit_action, object_type="campaign_version", object_id=version.id, details=audit_details, commit=True, ) _write_current_version_snapshot_if_available(version) return CampaignVersionDetailResponse.model_validate( version, context=_campaign_response_context(principal), ) except LockedCampaignVersionError as exc: session.rollback() raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail=str(exc)) from exc except CampaignPathSecurityError as exc: session.rollback() raise HTTPException(status_code=status.HTTP_422_UNPROCESSABLE_CONTENT, detail=str(exc)) from exc except CampaignPersistenceError as exc: session.rollback() raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=str(exc)) from exc except Exception as exc: session.rollback() if validation_error_status is None: raise raise HTTPException(status_code=validation_error_status, detail=str(exc)) from exc def _update_campaign_version_detail_response( session: Session, principal: ApiPrincipal, campaign_id: str, version_id: str, payload: CampaignVersionUpdateRequest, *, autosave: bool, audit_action: str, ) -> CampaignVersionDetailResponse: _get_campaign_for_principal(session, campaign_id, principal, write=True) current_version = _get_version_for_tenant(session, version_id, principal.tenant_id) if _recipient_sections_changed(current_version.raw_json, payload.campaign_json): _require_permission(principal, "campaigns:recipient:write") _require_mail_profile_use_if_needed(principal, payload.campaign_json) return _campaign_version_detail_response( session, principal, campaign_id, lambda: update_campaign_version( session, tenant_id=principal.tenant_id, campaign_id=campaign_id, version_id=version_id, raw_json=payload.campaign_json, current_flow=payload.current_flow, current_step=payload.current_step, workflow_state=payload.workflow_state, is_complete=payload.is_complete, editor_state=payload.editor_state, source_filename=payload.source_filename, source_base_path=payload.source_base_path, autosave=autosave, migrate_legacy_mail_settings=payload.migrate_legacy_mail_settings, commit=False, ), audit_action=audit_action, details=lambda version: { "campaign_id": campaign_id, "current_flow": version.current_flow, "current_step": version.current_step, "legacy_mail_settings_migrated": payload.migrate_legacy_mail_settings, }, validation_error_status=status.HTTP_422_UNPROCESSABLE_CONTENT, ) def _require_campaign_profile_use_if_needed( session: Session, principal: ApiPrincipal, campaign_id: str, version_id: str | None = None, ) -> None: campaign = _get_campaign_for_tenant(session, campaign_id, principal.tenant_id) target_version_id = version_id or campaign.current_version_id if not target_version_id: return version = _get_version_for_tenant(session, target_version_id, principal.tenant_id) if version.campaign_id != campaign.id: raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Campaign version not found") _require_mail_profile_use_if_needed(principal, version.raw_json if isinstance(version.raw_json, dict) else {}) def _require_campaign_versions_profile_use( session: Session, principal: ApiPrincipal, campaign_id: str, version_ids: set[str], ) -> None: """Authorize every historical version affected by a campaign-wide action.""" for version_id in sorted(version_ids): _require_campaign_profile_use_if_needed( session, principal, campaign_id, version_id, ) def _get_version_for_principal( session: Session, version_id: str, principal: ApiPrincipal, *, write: bool = False, ) -> CampaignVersion: version = _get_version_for_tenant(session, version_id, principal.tenant_id) campaign = _get_campaign_for_tenant(session, version.campaign_id, principal.tenant_id) _require_campaign_acl(session, campaign, principal, write=write) return version def _sync_campaign_metadata_to_current_version(session: Session, campaign: Campaign) -> None: """Keep editable version JSON aligned with version-independent campaign metadata. Campaign metadata can be edited from the overview while individual campaign sections save the current version JSON later. Without this sync, a later version save can re-apply stale `campaign.name` / `campaign.id` values from raw_json and make the old overview metadata appear to come back. Audit-safe or validation-locked versions are left untouched. """ if not campaign.current_version_id: return version = session.get(CampaignVersion, campaign.current_version_id) if not version or version.campaign_id != campaign.id or is_version_locked(version): return raw_json = copy.deepcopy(version.raw_json if isinstance(version.raw_json, dict) else {}) campaign_section = raw_json.get("campaign") if isinstance(raw_json.get("campaign"), dict) else {} raw_json["campaign"] = { **campaign_section, "id": campaign.external_id, "name": campaign.name, "description": campaign.description or "", } version.raw_json = raw_json session.add(version) def _clear_current_version_mail_profile_for_owner_transfer(session: Session, campaign: Campaign) -> bool: """Force explicit profile reselection after campaign ownership changes. User/group-scoped reusable mail profiles are evaluated against the current owner. Instead of trying to keep a stale selection across an ownership transfer, clear the profile from the editable current version and invalidate validation/build state so the operator has to reselect and revalidate. """ if not campaign.current_version_id: return False version = session.get(CampaignVersion, campaign.current_version_id) if not version or version.campaign_id != campaign.id: return False raw_json = copy.deepcopy(version.raw_json if isinstance(version.raw_json, dict) else {}) server = raw_json.get("server") if isinstance(raw_json.get("server"), dict) else None if not isinstance(server, dict): return False profile_id = _campaign_mail_profile_id(raw_json) if not profile_id: return False if is_version_final_locked(version) or is_user_locked_version(version): raise HTTPException( status_code=status.HTTP_422_UNPROCESSABLE_CONTENT, detail="Change owner only after creating an editable campaign version; the current version has a selected mail profile and is locked.", ) next_server = dict(server) for key in CAMPAIGN_MAIL_SERVER_KEYS: next_server.pop(key, None) next_server.pop("profile_id", None) raw_json["server"] = next_server version.raw_json = raw_json version.validation_summary = None version.build_summary = None clear_execution_snapshot(version) version.locked_at = None version.locked_by_user_id = None version.workflow_state = CampaignVersionWorkflowState.EDITING.value version.is_complete = False editor_state = copy.deepcopy(version.editor_state or {}) editor_state.pop("review_send", None) version.editor_state = editor_state session.query(CampaignIssue).filter(CampaignIssue.campaign_version_id == version.id).delete(synchronize_session=False) session.query(CampaignJob).filter(CampaignJob.campaign_version_id == version.id).delete(synchronize_session=False) campaign.status = CampaignStatus.DRAFT.value session.add(version) _write_current_version_snapshot_if_available(version) return True def _write_current_version_snapshot_if_available(version: CampaignVersion) -> None: try: from govoplan_campaign.backend.persistence.campaigns import _write_campaign_snapshot _write_campaign_snapshot(version) except Exception: # The database state is authoritative for the WebUI. Snapshot writing is # best-effort here because ownership changes should not fail due to an # unavailable local runtime directory. return @router.post("", response_model=CampaignCreateResponse) def create_campaign( payload: CampaignCreateRequest, session: Session = Depends(get_session), principal: ApiPrincipal = Depends(require_scope("campaigns:campaign:create")), ): try: if payload.config.get("entries") or payload.config.get("recipients"): _require_permission(principal, "campaigns:recipient:write") _require_mail_profile_use_if_needed(principal, payload.config) campaign, version = create_campaign_version_from_json( session, tenant_id=principal.tenant_id, user_id=principal.user.id, raw_json=payload.config, source_filename=payload.source_filename, source_base_path=payload.source_base_path, commit=False, ) audit_from_principal( session, principal, action="campaign.created", object_type="campaign", object_id=campaign.id, details={"version_id": version.id, "external_id": campaign.external_id}, commit=True, ) _write_current_version_snapshot_if_available(version) except HTTPException: session.rollback() raise except Exception as exc: session.rollback() raise HTTPException(status_code=status.HTTP_422_UNPROCESSABLE_CONTENT, detail=str(exc)) from exc return CampaignCreateResponse( campaign=CampaignResponse.model_validate(campaign), version=CampaignVersionResponse.model_validate( version, context=_campaign_response_context(principal), ), ) @router.post("/new", response_model=CampaignCreateResponse) def create_minimal_campaign_endpoint( payload: CampaignCreateMinimalRequest, session: Session = Depends(get_session), principal: ApiPrincipal = Depends(require_scope("campaigns:campaign:create")), ): """Create a minimal editable campaign/version for the WebUI wizard. This is intentionally different from importing a complete campaign JSON. It returns a normal Campaign + CampaignVersion whose version is a working copy and can be autosaved while incomplete. """ try: campaign, version = create_minimal_campaign( session, tenant_id=principal.tenant_id, user_id=principal.user.id, external_id=payload.external_id, name=payload.name, description=payload.description, current_flow=payload.current_flow, current_step=payload.current_step, commit=False, ) audit_from_principal( session, principal, action="campaign.created_minimal", object_type="campaign", object_id=campaign.id, details={"version_id": version.id, "external_id": campaign.external_id}, commit=True, ) _write_current_version_snapshot_if_available(version) return CampaignCreateResponse( campaign=CampaignResponse.model_validate(campaign), version=CampaignVersionResponse.model_validate( version, context=_campaign_response_context(principal), ), ) except CampaignPersistenceError as exc: session.rollback() raise HTTPException(status_code=status.HTTP_422_UNPROCESSABLE_CONTENT, detail=str(exc)) from exc except Exception: session.rollback() raise @router.get("", response_model=CampaignListResponse) def list_campaigns( limit: int = 200, session: Session = Depends(get_session), principal: ApiPrincipal = Depends(require_scope("campaigns:campaign:read")), ): campaigns = ( _campaign_query_for_principal(session, principal) .order_by(Campaign.updated_at.desc()) .limit(max(1, min(limit, 500))) .all() ) return CampaignListResponse(campaigns=[CampaignResponse.model_validate(item) for item in campaigns]) def _bounded_query_rows(query, *, limit: int, label: str): rows = query.limit(limit + 1).all() if len(rows) > limit: raise HTTPException( status_code=status.HTTP_413_CONTENT_TOO_LARGE, detail=( f"{label} exceeds the maximum response size of {limit} rows. " "Narrow the request or use a paginated/delta endpoint." ), ) return rows def _job_attempt_rows(query, *, label: str): return _bounded_query_rows(query, limit=1000, label=label) _CAMPAIGN_LIST_DELTA_COLLECTIONS = (CAMPAIGNS_COLLECTION,) _CAMPAIGN_FULL_CURSOR_PREFIX = "full:campaigns:" _CAMPAIGN_WORKSPACE_DELTA_COLLECTIONS = ( CAMPAIGNS_COLLECTION, CAMPAIGN_VERSIONS_COLLECTION, CAMPAIGN_JOBS_COLLECTION, CAMPAIGN_ISSUES_COLLECTION, CAMPAIGN_ATTEMPTS_COLLECTION, ) @dataclasses.dataclass(frozen=True, slots=True) class _WorkspaceDeltaState: entries: list[object] relevant_entries: list[object] has_more: bool changed_campaign: bool changed_version_ids: set[str] selected_version_id: str | None changed_current_version: bool summary_invalidated: bool def _campaign_delta_watermark(session: Session, tenant_id: str, collections: tuple[str, ...]) -> str: return encode_sequence_watermark( max_sequence_id( session, tenant_id=tenant_id, module_id=CAMPAIGNS_MODULE_ID, collections=collections, ) ) def _campaign_entry_matches_principal(session: Session, principal: ApiPrincipal, payload: dict[str, object]) -> bool: if has_scope(principal, "tenant:*"): return True user_ids = { value for value in (payload.get("owner_user_id"), payload.get("previous_owner_user_id")) if isinstance(value, str) } if principal.user.id in user_ids: return True group_ids = _principal_group_ids(session, principal) owner_group_ids = { value for value in (payload.get("owner_group_id"), payload.get("previous_owner_group_id")) if isinstance(value, str) } if owner_group_ids.intersection(group_ids): return True share_target_type = payload.get("share_target_type") share_target_id = payload.get("share_target_id") if share_target_type == "user" and share_target_id == principal.user.id: return True if share_target_type == "group" and isinstance(share_target_id, str) and share_target_id in group_ids: return True return False def _campaign_full_cursor( *, page: int, snapshot_sequence: int, ) -> str: return ( f"{_CAMPAIGN_FULL_CURSOR_PREFIX}" f"{int(page)}:{int(snapshot_sequence)}" ) def _decode_campaign_full_cursor( value: str | None, ) -> tuple[int, int] | None: if not value or not value.startswith(_CAMPAIGN_FULL_CURSOR_PREFIX): return None parts = value[len(_CAMPAIGN_FULL_CURSOR_PREFIX):].split(":", 1) if len(parts) != 2: raise HTTPException( status_code=status.HTTP_400_BAD_REQUEST, detail="Invalid campaign full snapshot cursor", ) try: page, snapshot_sequence = (int(item) for item in parts) except ValueError as exc: raise HTTPException( status_code=status.HTTP_400_BAD_REQUEST, detail="Invalid campaign full snapshot cursor", ) from exc if page < 1 or snapshot_sequence < 0: raise HTTPException( status_code=status.HTTP_400_BAD_REQUEST, detail="Invalid campaign full snapshot cursor", ) return page, snapshot_sequence def _campaign_list_full_delta_response( session: Session, principal: ApiPrincipal, *, cursor: tuple[int, int] | None = None, limit: int = 500, ) -> CampaignDeltaResponse: page = cursor[0] if cursor is not None else 1 snapshot_sequence = ( cursor[1] if cursor is not None else decode_sequence_watermark( _campaign_delta_watermark( session, principal.tenant_id, _CAMPAIGN_LIST_DELTA_COLLECTIONS, ), ) ) query = _campaign_query_for_principal(session, principal) total = query.order_by(None).count() pages = max(1, (total + limit - 1) // limit) campaigns = ( query.order_by(Campaign.updated_at.desc(), Campaign.id.asc()) .offset((page - 1) * limit) .limit(limit) .all() ) has_more = page < pages return CampaignDeltaResponse( campaigns=[CampaignResponse.model_validate(item) for item in campaigns], deleted=[], watermark=( _campaign_full_cursor( page=page + 1, snapshot_sequence=snapshot_sequence, ) if has_more else encode_sequence_watermark(snapshot_sequence) ), has_more=has_more, full=True, total=total, page=page, page_size=limit, pages=pages, ) def _campaign_list_delta_response(session: Session, principal: ApiPrincipal, *, since: str, limit: int) -> CampaignDeltaResponse: try: since_sequence = decode_sequence_watermark(since) except ValueError as exc: raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(exc)) from exc if sequence_watermark_is_expired( session, since=since_sequence, tenant_id=principal.tenant_id, module_id=CAMPAIGNS_MODULE_ID, collections=_CAMPAIGN_LIST_DELTA_COLLECTIONS, ): return _campaign_list_full_delta_response( session, principal, limit=limit, ) entries_plus_one = sequence_entries_since( session, since=since_sequence, tenant_id=principal.tenant_id, module_id=CAMPAIGNS_MODULE_ID, collections=_CAMPAIGN_LIST_DELTA_COLLECTIONS, limit=limit + 1, ) has_more = len(entries_plus_one) > limit entries = entries_plus_one[:limit] changed_ids = list(dict.fromkeys(entry.resource_id for entry in entries if entry.resource_type == "campaign")) visible_campaigns = { campaign.id: campaign for campaign in ( _campaign_query_for_principal(session, principal) .filter(Campaign.id.in_(changed_ids)) .order_by(Campaign.updated_at.desc()) .all() if changed_ids else [] ) } deleted: dict[tuple[str, str], DeltaDeletedItem] = {} for entry in entries: if entry.resource_type != "campaign" or entry.resource_id in visible_campaigns: continue payload = entry.payload or {} if not _campaign_entry_matches_principal(session, principal, payload): continue deleted[(entry.resource_type, entry.resource_id)] = DeltaDeletedItem( id=entry.resource_id, resource_type=entry.resource_type, revision=encode_sequence_watermark(entry.id), deleted_at=entry.created_at if entry.operation == "deleted" else None, ) watermark = ( encode_sequence_watermark(entries[-1].id) if has_more and entries else _campaign_delta_watermark(session, principal.tenant_id, _CAMPAIGN_LIST_DELTA_COLLECTIONS) ) return CampaignDeltaResponse( campaigns=[CampaignResponse.model_validate(item) for item in visible_campaigns.values()], deleted=list(deleted.values()), watermark=watermark, has_more=has_more, full=False, total=len(visible_campaigns), page=1, page_size=limit, pages=1, ) @router.get("/delta", response_model=CampaignDeltaResponse) def list_campaigns_delta( since: str | None = None, limit: int = Query(default=500, ge=1, le=1000), session: Session = Depends(get_session), principal: ApiPrincipal = Depends(require_scope("campaigns:campaign:read")), ): full_cursor = _decode_campaign_full_cursor(since) if since is None or full_cursor is not None: return _campaign_list_full_delta_response( session, principal, cursor=full_cursor, limit=limit, ) return _campaign_list_delta_response(session, principal, since=since, limit=limit) @router.get("/recipient-import/mapping-profiles", response_model=RecipientImportMappingProfileListResponse) def list_recipient_import_mapping_profiles( limit: int = Query(default=200, ge=1, le=1000), session: Session = Depends(get_session), principal: ApiPrincipal = Depends(require_scope("campaigns:recipient:import")), ): profiles = _bounded_query_rows( session.query(RecipientImportMappingProfile) .filter( RecipientImportMappingProfile.tenant_id == principal.tenant_id, RecipientImportMappingProfile.owner_user_id == principal.user.id, ) .order_by( RecipientImportMappingProfile.updated_at.desc(), RecipientImportMappingProfile.name.asc(), ), limit=limit, label="Recipient import mapping profile list", ) return RecipientImportMappingProfileListResponse( profiles=[RecipientImportMappingProfileResponse.model_validate(profile) for profile in profiles] ) @router.post( "/recipient-import/mapping-profiles", response_model=RecipientImportMappingProfileResponse, status_code=status.HTTP_201_CREATED, ) def create_recipient_import_mapping_profile( payload: RecipientImportMappingProfilePayload, session: Session = Depends(get_session), principal: ApiPrincipal = Depends(require_scope("campaigns:recipient:import")), ): profile = RecipientImportMappingProfile( tenant_id=principal.tenant_id, owner_user_id=principal.user.id, name=payload.name.strip(), column_count=payload.column_count, headers=list(payload.headers), normalized_headers=list(payload.normalized_headers), ordered_header_fingerprint=payload.ordered_header_fingerprint, unordered_header_fingerprint=payload.unordered_header_fingerprint, delimiter=payload.delimiter, header_rows=payload.header_rows, quoted=payload.quoted, value_separators=payload.value_separators, mappings=[mapping.model_dump(mode="json") for mapping in payload.mappings], ) session.add(profile) session.flush() audit_from_principal( session, principal, action="campaign.recipient_import_mapping_profile_created", object_type="recipient_import_mapping_profile", object_id=profile.id, details={"name": profile.name, "ordered_header_fingerprint": profile.ordered_header_fingerprint}, commit=True, ) session.refresh(profile) return RecipientImportMappingProfileResponse.model_validate(profile) @router.put("/recipient-import/mapping-profiles/{profile_id}", response_model=RecipientImportMappingProfileResponse) def update_recipient_import_mapping_profile( profile_id: str, payload: RecipientImportMappingProfilePayload, session: Session = Depends(get_session), principal: ApiPrincipal = Depends(require_scope("campaigns:recipient:import")), ): profile = _get_recipient_import_profile_for_principal(session, profile_id, principal) _apply_recipient_import_profile_payload(profile, payload) session.add(profile) audit_from_principal( session, principal, action="campaign.recipient_import_mapping_profile_updated", object_type="recipient_import_mapping_profile", object_id=profile.id, details={"name": profile.name, "ordered_header_fingerprint": profile.ordered_header_fingerprint}, commit=True, ) session.refresh(profile) return RecipientImportMappingProfileResponse.model_validate(profile) @router.delete("/recipient-import/mapping-profiles/{profile_id}", status_code=status.HTTP_204_NO_CONTENT) def delete_recipient_import_mapping_profile( profile_id: str, session: Session = Depends(get_session), principal: ApiPrincipal = Depends(require_scope("campaigns:recipient:import")), ): profile = _get_recipient_import_profile_for_principal(session, profile_id, principal) details = {"name": profile.name, "ordered_header_fingerprint": profile.ordered_header_fingerprint} session.delete(profile) audit_from_principal( session, principal, action="campaign.recipient_import_mapping_profile_deleted", object_type="recipient_import_mapping_profile", object_id=profile_id, details=details, commit=True, ) return Response(status_code=status.HTTP_204_NO_CONTENT) @router.get("/aggregate-reports", response_model=AggregateReportCampaignList) def list_aggregate_campaign_reports( limit: int = Query(default=500, ge=1, le=1000), session: Session = Depends(get_session), principal: ApiPrincipal = Depends(require_scope("campaigns:report:read")), ): """List only the business metadata needed to select an aggregate report.""" campaigns = _bounded_query_rows( _campaign_query_for_principal(session, principal) .order_by(Campaign.updated_at.desc(), Campaign.id.asc()), limit=limit, label="Aggregate report campaign list", ) return AggregateReportCampaignList( campaigns=[aggregate_report_campaign_item(campaign) for campaign in campaigns] ) @router.get("/aggregate-reports/{campaign_id}", response_model=AggregateCampaignReport) def aggregate_campaign_report( campaign_id: str, version_id: str | None = None, session: Session = Depends(get_session), principal: ApiPrincipal = Depends(require_scope("campaigns:report:read")), ): """Return the privacy-safe aggregate projection without recipient detail.""" _get_campaign_for_principal(session, campaign_id, principal) try: return generate_aggregate_campaign_report( session, tenant_id=principal.tenant_id, campaign_id=campaign_id, version_id=version_id, ) except AggregateCampaignReportError as exc: raise HTTPException( status_code=status.HTTP_404_NOT_FOUND, detail="Campaign report not found", ) from exc except CampaignReportPrivacyPolicyError as exc: raise HTTPException( status_code=status.HTTP_503_SERVICE_UNAVAILABLE, detail="Campaign report privacy policy is invalid", ) from exc @router.get("/{campaign_id}/address-lookup", response_model=CampaignAddressLookupResponse) def lookup_campaign_addresses( campaign_id: str, query: str = Query(default="", min_length=0), limit: int = Query(default=25, ge=1, le=100), session: Session = Depends(get_session), principal: ApiPrincipal = Depends(require_scope("campaigns:recipient:read")), ): _get_campaign_for_principal(session, campaign_id, principal) capability = _registry_capability(CAPABILITY_ADDRESSES_LOOKUP) if capability is None or not hasattr(capability, "lookup"): return CampaignAddressLookupResponse(available=False, candidates=[]) candidates = getattr(capability, "lookup")(session, principal, query=query, limit=limit) return CampaignAddressLookupResponse( available=True, candidates=[CampaignAddressLookupCandidate.model_validate(_capability_payload(candidate)) for candidate in candidates], ) @router.get("/{campaign_id}/recipient-address-sources", response_model=CampaignRecipientAddressSourcesResponse) def list_campaign_recipient_address_sources( campaign_id: str, session: Session = Depends(get_session), principal: ApiPrincipal = Depends(require_scope("campaigns:recipient:read")), ): _get_campaign_for_principal(session, campaign_id, principal) capability = _registry_capability(CAPABILITY_ADDRESSES_RECIPIENT_SOURCE) if capability is None or not hasattr(capability, "list_sources"): return CampaignRecipientAddressSourcesResponse(available=False, sources=[]) sources = getattr(capability, "list_sources")(session, principal) return CampaignRecipientAddressSourcesResponse( available=True, sources=[CampaignRecipientAddressSource.model_validate(_capability_payload(source)) for source in sources], ) @router.get( "/{campaign_id}/postbox-catalog", response_model=CampaignPostboxCatalogResponse, ) def campaign_postbox_catalog( campaign_id: str, session: Session = Depends(get_session), principal: ApiPrincipal = Depends( require_scope("campaigns:recipient:write") ), ): _get_campaign_for_principal(session, campaign_id, principal, write=True) integration = postbox_integration() if not integration.available: return CampaignPostboxCatalogResponse(available=False) try: payload = delivery_catalog_payload( integration.delivery_catalog( session, tenant_id=principal.tenant_id, ) ) except PostboxDeliveryUnavailable: return CampaignPostboxCatalogResponse(available=False) return CampaignPostboxCatalogResponse( available=True, postboxes=payload.get("postboxes", []), templates=payload.get("templates", []), organization_units=payload.get("organization_units", []), ) @router.post("/{campaign_id}/recipient-address-sources/snapshot", response_model=CampaignRecipientAddressSourceSnapshotResponse) def snapshot_campaign_recipient_address_source( campaign_id: str, payload: CampaignRecipientAddressSourceSnapshotRequest, session: Session = Depends(get_session), principal: ApiPrincipal = Depends(require_scope("campaigns:recipient:import")), ): _get_campaign_for_principal(session, campaign_id, principal, write=True) capability = _registry_capability(CAPABILITY_ADDRESSES_RECIPIENT_SOURCE) if capability is None or not hasattr(capability, "snapshot"): raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Address recipient-source capability is not available") try: snapshot = getattr(capability, "snapshot")(session, principal, source_id=payload.source_id) except ValueError as exc: raise HTTPException(status_code=status.HTTP_422_UNPROCESSABLE_CONTENT, detail=str(exc)) from exc snapshot_payload = _capability_payload(snapshot) recipients = [ CampaignRecipientSnapshotItem.model_validate(_capability_payload(item)) for item in snapshot_payload.get("recipients", []) ] return CampaignRecipientAddressSourceSnapshotResponse( source_id=str(snapshot_payload.get("source_id") or ""), source_label=str(snapshot_payload.get("source_label") or ""), source_kind=str(snapshot_payload.get("source_kind") or ""), source_revision=str(snapshot_payload.get("source_revision") or ""), generated_at=str(snapshot_payload.get("generated_at") or ""), recipients=recipients, provenance=snapshot_payload.get("provenance") if isinstance(snapshot_payload.get("provenance"), dict) else {}, ) @router.get("/{campaign_id}", response_model=CampaignResponse) def get_campaign( campaign_id: str, session: Session = Depends(get_session), principal: ApiPrincipal = Depends(require_scope("campaigns:campaign:read")), ): return CampaignResponse.model_validate(_get_campaign_for_principal(session, campaign_id, principal)) def _campaign_workspace_response( session: Session, principal: ApiPrincipal, *, campaign_id: str, version_id: str | None, include_current_version: bool, include_summary: bool, include_versions: bool, ) -> CampaignWorkspaceResponse: campaign = _get_campaign_for_principal(session, campaign_id, principal) versions: list[CampaignVersion] = [] if include_versions or include_current_version: versions = _bounded_query_rows( session.query(CampaignVersion) .filter(CampaignVersion.campaign_id == campaign.id) .order_by(CampaignVersion.version_number.desc()), limit=1000, label="Campaign version history", ) selected_version_id = version_id or campaign.current_version_id or (versions[0].id if versions else None) current_version: CampaignVersion | None = None if include_current_version and selected_version_id: _require_permission(principal, "campaigns:recipient:read") current_version = ( session.query(CampaignVersion) .filter( CampaignVersion.id == selected_version_id, CampaignVersion.campaign_id == campaign.id, ) .one_or_none() ) summary_payload: dict[str, object] | None = None if include_summary: try: summary_payload = generate_campaign_report( session, tenant_id=principal.tenant_id, campaign_id=campaign_id, version_id=selected_version_id, include_jobs=False, include_diagnostics=has_scope(principal, "campaigns:diagnostic:read"), ) except CampaignReportError: summary_payload = None return CampaignWorkspaceResponse( campaign=CampaignResponse.model_validate(campaign), versions=[ CampaignVersionResponse.model_validate( item, context=_campaign_response_context(principal), ) for item in versions ] if include_versions else [], current_version=( CampaignVersionDetailResponse.model_validate( current_version, context=_campaign_response_context(principal), ) if current_version is not None else None ), summary=summary_payload, selected_version_id=selected_version_id, ) @router.get("/{campaign_id}/workspace", response_model=CampaignWorkspaceResponse) def get_campaign_workspace( campaign_id: str, version_id: str | None = None, include_current_version: bool = True, include_summary: bool = False, include_versions: bool = True, session: Session = Depends(get_session), principal: ApiPrincipal = Depends(require_scope("campaigns:campaign:read")), ): return _campaign_workspace_response( session, principal, campaign_id=campaign_id, version_id=version_id, include_current_version=include_current_version, include_summary=include_summary, include_versions=include_versions, ) def _workspace_delta_deleted_item(entry) -> DeltaDeletedItem: return DeltaDeletedItem( id=entry.resource_id, resource_type=entry.resource_type, revision=encode_sequence_watermark(entry.id), deleted_at=entry.created_at if entry.operation == "deleted" else None, ) def _entry_belongs_to_campaign(entry, campaign_id: str) -> bool: payload = entry.payload or {} if payload.get("campaign_id") == campaign_id: return True return entry.resource_type == "campaign" and entry.resource_id == campaign_id def _campaign_workspace_full_delta_response( session: Session, principal: ApiPrincipal, *, campaign_id: str, version_id: str | None, include_current_version: bool, include_summary: bool, include_versions: bool, ) -> CampaignWorkspaceDeltaResponse: payload = _campaign_workspace_response( session, principal, campaign_id=campaign_id, version_id=version_id, include_current_version=include_current_version, include_summary=include_summary, include_versions=include_versions, ) return CampaignWorkspaceDeltaResponse( **payload.model_dump(), deleted=[], watermark=_campaign_delta_watermark(session, principal.tenant_id, _CAMPAIGN_WORKSPACE_DELTA_COLLECTIONS), has_more=False, full=True, ) def _campaign_workspace_delta_response( session: Session, principal: ApiPrincipal, *, campaign_id: str, version_id: str | None, include_current_version: bool, include_summary: bool, include_versions: bool, since: str, limit: int, ) -> CampaignWorkspaceDeltaResponse: campaign = _get_campaign_for_principal(session, campaign_id, principal) try: since_sequence = decode_sequence_watermark(since) except ValueError as exc: raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(exc)) from exc if sequence_watermark_is_expired( session, since=since_sequence, tenant_id=principal.tenant_id, module_id=CAMPAIGNS_MODULE_ID, collections=_CAMPAIGN_WORKSPACE_DELTA_COLLECTIONS, ): return _campaign_workspace_full_delta_response( session, principal, campaign_id=campaign_id, version_id=version_id, include_current_version=include_current_version, include_summary=include_summary, include_versions=include_versions, ) delta = _campaign_workspace_delta_state( session, principal, campaign=campaign, version_id=version_id, since_sequence=since_sequence, limit=limit, ) return CampaignWorkspaceDeltaResponse( campaign=CampaignResponse.model_validate(campaign) if delta.changed_campaign else None, versions=_campaign_workspace_delta_versions( session, principal, campaign, delta, include_versions=include_versions, ), current_version=_campaign_workspace_delta_current_version( session, principal, campaign=campaign, delta=delta, include_current_version=include_current_version, ), summary=_campaign_workspace_delta_summary( session, principal, campaign_id=campaign_id, delta=delta, include_summary=include_summary, ), selected_version_id=delta.selected_version_id, deleted=_campaign_workspace_delta_deleted(delta.relevant_entries), watermark=_campaign_workspace_delta_watermark(session, principal, delta), has_more=delta.has_more, full=False, ) def _campaign_workspace_delta_state( session: Session, principal: ApiPrincipal, *, campaign: Campaign, version_id: str | None, since_sequence: int, limit: int, ) -> _WorkspaceDeltaState: entries_plus_one = sequence_entries_since( session, since=since_sequence, tenant_id=principal.tenant_id, module_id=CAMPAIGNS_MODULE_ID, collections=_CAMPAIGN_WORKSPACE_DELTA_COLLECTIONS, limit=limit + 1, ) entries = entries_plus_one[:limit] relevant_entries = [entry for entry in entries if _entry_belongs_to_campaign(entry, campaign.id)] changed_version_ids = { entry.resource_id for entry in relevant_entries if entry.resource_type == "campaign_version" and entry.operation != "deleted" } selected_version_id = version_id or campaign.current_version_id return _WorkspaceDeltaState( entries=entries, relevant_entries=relevant_entries, has_more=len(entries_plus_one) > limit, changed_campaign=any(entry.resource_type == "campaign" for entry in relevant_entries), changed_version_ids=changed_version_ids, selected_version_id=selected_version_id, changed_current_version=bool(selected_version_id and selected_version_id in changed_version_ids), summary_invalidated=any( entry.collection in {CAMPAIGN_JOBS_COLLECTION, CAMPAIGN_ISSUES_COLLECTION, CAMPAIGN_ATTEMPTS_COLLECTION} for entry in relevant_entries ), ) def _campaign_workspace_delta_deleted(entries: list[object]) -> list[dict[str, object]]: return [ _workspace_delta_deleted_item(entry) for entry in entries if entry.operation == "deleted" and entry.resource_type != "campaign" ] def _campaign_workspace_delta_versions( session: Session, principal: ApiPrincipal, campaign: Campaign, delta: _WorkspaceDeltaState, *, include_versions: bool, ) -> list[CampaignVersionResponse]: if not include_versions or not delta.changed_version_ids: return [] versions = ( session.query(CampaignVersion) .filter(CampaignVersion.campaign_id == campaign.id, CampaignVersion.id.in_(delta.changed_version_ids)) .order_by(CampaignVersion.version_number.desc()) .all() ) return [ CampaignVersionResponse.model_validate( item, context=_campaign_response_context(principal), ) for item in versions ] def _campaign_workspace_delta_current_version( session: Session, principal: ApiPrincipal, *, campaign: Campaign, delta: _WorkspaceDeltaState, include_current_version: bool, ) -> CampaignVersionDetailResponse | None: if not include_current_version or not delta.selected_version_id: return None if not (delta.changed_campaign or delta.changed_current_version): return None _require_permission(principal, "campaigns:recipient:read") current_version = ( session.query(CampaignVersion) .filter(CampaignVersion.id == delta.selected_version_id, CampaignVersion.campaign_id == campaign.id) .one_or_none() ) return ( CampaignVersionDetailResponse.model_validate( current_version, context=_campaign_response_context(principal), ) if current_version is not None else None ) def _campaign_workspace_delta_summary( session: Session, principal: ApiPrincipal, *, campaign_id: str, delta: _WorkspaceDeltaState, include_summary: bool, ) -> dict[str, object] | None: if not include_summary: return None if not (delta.changed_campaign or delta.changed_version_ids or delta.summary_invalidated): return None try: return generate_campaign_report( session, tenant_id=principal.tenant_id, campaign_id=campaign_id, version_id=delta.selected_version_id, include_jobs=False, include_diagnostics=has_scope(principal, "campaigns:diagnostic:read"), ) except CampaignReportError: return None def _campaign_workspace_delta_watermark( session: Session, principal: ApiPrincipal, delta: _WorkspaceDeltaState, ) -> str: if delta.has_more and delta.entries: return encode_sequence_watermark(delta.entries[-1].id) return _campaign_delta_watermark(session, principal.tenant_id, _CAMPAIGN_WORKSPACE_DELTA_COLLECTIONS) @router.get("/{campaign_id}/workspace/delta", response_model=CampaignWorkspaceDeltaResponse) def get_campaign_workspace_delta( campaign_id: str, version_id: str | None = None, include_current_version: bool = True, include_summary: bool = False, include_versions: bool = True, since: str | None = None, limit: int = Query(default=500, ge=1, le=1000), session: Session = Depends(get_session), principal: ApiPrincipal = Depends(require_scope("campaigns:campaign:read")), ): if since is None: return _campaign_workspace_full_delta_response( session, principal, campaign_id=campaign_id, version_id=version_id, include_current_version=include_current_version, include_summary=include_summary, include_versions=include_versions, ) return _campaign_workspace_delta_response( session, principal, campaign_id=campaign_id, version_id=version_id, include_current_version=include_current_version, include_summary=include_summary, include_versions=include_versions, since=since, limit=limit, ) @router.put("/{campaign_id}", response_model=CampaignResponse) def update_campaign_metadata_endpoint( campaign_id: str, payload: CampaignUpdateRequest, session: Session = Depends(get_session), principal: ApiPrincipal = Depends(require_scope("campaigns:campaign:update")), ): campaign = _get_campaign_for_principal(session, campaign_id, principal, write=True) if payload.external_id is not None: value = payload.external_id.strip() if not value: raise HTTPException(status_code=status.HTTP_422_UNPROCESSABLE_CONTENT, detail="Campaign ID cannot be empty") duplicate = ( session.query(Campaign) .filter(Campaign.tenant_id == principal.tenant_id, Campaign.external_id == value, Campaign.id != campaign.id) .one_or_none() ) if duplicate: raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail="Campaign ID already exists for this tenant") campaign.external_id = value if payload.name is not None: value = payload.name.strip() if not value: raise HTTPException(status_code=status.HTTP_422_UNPROCESSABLE_CONTENT, detail="Campaign name cannot be empty") campaign.name = value if payload.status is not None: campaign.status = payload.status if payload.description is not None: campaign.description = payload.description _sync_campaign_metadata_to_current_version(session, campaign) session.add(campaign) session.flush() try: audit_from_principal( session, principal, action="campaign.metadata_updated", object_type="campaign", object_id=campaign.id, details={"external_id": campaign.external_id, "name": campaign.name}, commit=True, ) except Exception: session.rollback() raise session.refresh(campaign) if campaign.current_version_id: current_version = session.get(CampaignVersion, campaign.current_version_id) if current_version is not None: _write_current_version_snapshot_if_available(current_version) return CampaignResponse.model_validate(campaign) @router.post("/{campaign_id}/archive", response_model=CampaignResponse) def archive_campaign( campaign_id: str, session: Session = Depends(get_session), principal: ApiPrincipal = Depends(require_scope("campaigns:campaign:archive")), ): campaign = _get_campaign_for_principal(session, campaign_id, principal, write=True) if campaign.status in {"queued", "sending", "outcome_unknown"}: raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail="Active or uncertain delivery must be resolved before archiving.") campaign.status = "archived" session.add(campaign) audit_from_principal( session, principal, action="campaign.archived", object_type="campaign", object_id=campaign.id, details={}, commit=True ) session.refresh(campaign) return CampaignResponse.model_validate(campaign) @router.delete("/{campaign_id}", status_code=status.HTTP_204_NO_CONTENT) def delete_draft_campaign( campaign_id: str, session: Session = Depends(get_session), principal: ApiPrincipal = Depends(require_scope("campaigns:campaign:delete")), ): campaign = _get_campaign_for_principal(session, campaign_id, principal, write=True) if campaign.status != "draft": raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail="Only untouched draft campaigns can be deleted.") if session.query(CampaignJob.id).filter(CampaignJob.campaign_id == campaign.id).first() is not None: raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail="Campaigns with built or delivery jobs must be archived instead of deleted.") protected_version = ( session.query(CampaignVersion.id) .filter( CampaignVersion.campaign_id == campaign.id, or_( CampaignVersion.locked_at.is_not(None), CampaignVersion.user_lock_state.is_not(None), CampaignVersion.published_at.is_not(None), CampaignVersion.execution_snapshot_at.is_not(None), ), ) .first() ) if protected_version is not None: raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail="Audit-relevant campaign versions must be archived instead of deleted.") campaign.status = "deleted" session.add(campaign) audit_from_principal( session, principal, action="campaign.deleted", object_type="campaign", object_id=campaign.id, details={"mode": "soft"}, commit=True ) return Response(status_code=status.HTTP_204_NO_CONTENT) @router.get("/{campaign_id}/versions", response_model=list[CampaignVersionResponse]) def list_versions( campaign_id: str, limit: int = Query(default=500, ge=1, le=1000), session: Session = Depends(get_session), principal: ApiPrincipal = Depends(require_scope("campaigns:campaign:read")), ): _get_campaign_for_principal(session, campaign_id, principal) campaign = _get_campaign_for_tenant(session, campaign_id, principal.tenant_id) versions = _bounded_query_rows( session.query(CampaignVersion) .filter(CampaignVersion.campaign_id == campaign.id) .order_by(CampaignVersion.version_number.desc()), limit=limit, label="Campaign version history", ) return [ CampaignVersionResponse.model_validate( item, context=_campaign_response_context(principal), ) for item in versions ] @router.get("/{campaign_id}/versions/{version_id}", response_model=CampaignVersionDetailResponse) def get_version_detail( campaign_id: str, version_id: str, session: Session = Depends(get_session), principal: ApiPrincipal = Depends(require_scope("campaigns:campaign:read")), ): _get_campaign_for_principal(session, campaign_id, principal) _require_permission(principal, "campaigns:recipient:read") try: version = get_campaign_version_for_tenant( session, tenant_id=principal.tenant_id, campaign_id=campaign_id, version_id=version_id ) return CampaignVersionDetailResponse.model_validate( version, context=_campaign_response_context(principal), ) except CampaignPersistenceError as exc: raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=str(exc)) from exc @router.post("/{campaign_id}/versions/{version_id}/fork", response_model=CampaignCreateResponse) def fork_version_for_edit( campaign_id: str, version_id: str, payload: CampaignVersionUpdateRequest | None = None, session: Session = Depends(get_session), principal: ApiPrincipal = Depends(require_scope("campaigns:campaign:copy")), ): """Create the campaign's next and only editable working version. A new working copy may be created only after the current version is permanently user-locked or delivery-final. Validation and temporary user locks must be removed in place instead of creating parallel drafts. """ _get_campaign_for_principal(session, campaign_id, principal, write=True) _require_permission(principal, "campaigns:recipient:read") payload = payload or CampaignVersionUpdateRequest() source_version = _get_version_for_tenant(session, version_id, principal.tenant_id) if source_version.campaign_id != campaign_id: raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Campaign version not found") effective_json = ( payload.campaign_json if isinstance(payload.campaign_json, dict) else source_version.raw_json ) _require_mail_profile_use_if_needed( principal, effective_json if isinstance(effective_json, dict) else {}, ) try: version = fork_campaign_version_for_edit( session, tenant_id=principal.tenant_id, campaign_id=campaign_id, version_id=version_id, raw_json=payload.campaign_json, current_flow=payload.current_flow or "manual", current_step=payload.current_step, editor_state=payload.editor_state, source_filename=payload.source_filename, source_base_path=payload.source_base_path, autosave=True, migrate_legacy_mail_settings=payload.migrate_legacy_mail_settings, commit=False, ) campaign = _get_campaign_for_tenant(session, campaign_id, principal.tenant_id) audit_from_principal( session, principal, action="campaign.version_forked_for_edit", object_type="campaign_version", object_id=version.id, details={ "campaign_id": campaign_id, "source_version_id": version_id, "version_number": version.version_number, "legacy_mail_settings_migrated": payload.migrate_legacy_mail_settings, }, commit=True, ) _write_current_version_snapshot_if_available(version) return CampaignCreateResponse( campaign=CampaignResponse.model_validate(campaign), version=CampaignVersionResponse.model_validate( version, context=_campaign_response_context(principal), ), ) except LockedCampaignVersionError as exc: session.rollback() raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail=str(exc)) from exc except CampaignPathSecurityError as exc: session.rollback() raise HTTPException(status_code=status.HTTP_422_UNPROCESSABLE_CONTENT, detail=str(exc)) from exc except CampaignPersistenceError as exc: session.rollback() raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=str(exc)) from exc except Exception: session.rollback() raise @router.post("/{campaign_id}/versions/{version_id}/unlock-validation", response_model=CampaignVersionDetailResponse) def unlock_version_validation( campaign_id: str, version_id: str, session: Session = Depends(get_session), principal: ApiPrincipal = Depends(require_scope("campaigns:campaign:update")), ): """Unlock a successfully validated version before delivery starts. Unlocking invalidates validation/build state and removes generated jobs for that version. Sent/final versions cannot be unlocked and must be copied. """ _get_campaign_for_principal(session, campaign_id, principal, write=True) return _campaign_version_detail_response( session, principal, campaign_id, lambda: unlock_validated_campaign_version( session, tenant_id=principal.tenant_id, campaign_id=campaign_id, version_id=version_id, commit=False, ), audit_action="campaign.version_validation_unlocked", ) @router.post("/{campaign_id}/versions/{version_id}/lock-temporarily", response_model=CampaignVersionDetailResponse) def lock_version_temporarily( campaign_id: str, version_id: str, session: Session = Depends(get_session), principal: ApiPrincipal = Depends(require_scope("campaigns:campaign:update")), ): _get_campaign_for_principal(session, campaign_id, principal, write=True) return _campaign_version_detail_response( session, principal, campaign_id, lambda: lock_campaign_version_temporarily( session, tenant_id=principal.tenant_id, campaign_id=campaign_id, version_id=version_id, user_id=principal.user.id, commit=False, ), audit_action="campaign.version_user_locked_temporarily", ) @router.post("/{campaign_id}/versions/{version_id}/unlock-user-lock", response_model=CampaignVersionDetailResponse) def unlock_version_user_lock( campaign_id: str, version_id: str, session: Session = Depends(get_session), principal: ApiPrincipal = Depends(require_scope("campaigns:campaign:update")), ): _get_campaign_for_principal(session, campaign_id, principal, write=True) return _campaign_version_detail_response( session, principal, campaign_id, lambda: unlock_user_locked_campaign_version( session, tenant_id=principal.tenant_id, campaign_id=campaign_id, version_id=version_id, commit=False, ), audit_action="campaign.version_user_lock_removed", ) @router.post("/{campaign_id}/versions/{version_id}/lock-permanently", response_model=CampaignVersionDetailResponse) def lock_version_permanently( campaign_id: str, version_id: str, session: Session = Depends(get_session), principal: ApiPrincipal = Depends(require_scope("campaigns:campaign:update")), ): _get_campaign_for_principal(session, campaign_id, principal, write=True) return _campaign_version_detail_response( session, principal, campaign_id, lambda: permanently_lock_campaign_version( session, tenant_id=principal.tenant_id, campaign_id=campaign_id, version_id=version_id, user_id=principal.user.id, commit=False, ), audit_action="campaign.version_user_locked_permanently", ) @router.put("/{campaign_id}/versions/{version_id}", response_model=CampaignVersionDetailResponse) def update_version_detail( campaign_id: str, version_id: str, payload: CampaignVersionUpdateRequest, session: Session = Depends(get_session), principal: ApiPrincipal = Depends(require_scope("campaigns:campaign:update")), ): return _update_campaign_version_detail_response( session, principal, campaign_id, version_id, payload, autosave=False, audit_action="campaign.version_updated", ) @router.post("/{campaign_id}/versions/{version_id}/autosave", response_model=CampaignVersionDetailResponse) def autosave_version( campaign_id: str, version_id: str, payload: CampaignVersionUpdateRequest, session: Session = Depends(get_session), principal: ApiPrincipal = Depends(require_scope("campaigns:campaign:update")), ): return _update_campaign_version_detail_response( session, principal, campaign_id, version_id, payload, autosave=True, audit_action="campaign.version_autosaved", ) @router.post("/{campaign_id}/versions/{version_id}/set-step", response_model=CampaignVersionDetailResponse) def set_version_step( campaign_id: str, version_id: str, payload: CampaignVersionSetStepRequest, session: Session = Depends(get_session), principal: ApiPrincipal = Depends(require_scope("campaigns:campaign:update")), ): _get_campaign_for_principal(session, campaign_id, principal, write=True) return _campaign_version_detail_response( session, principal, campaign_id, lambda: update_campaign_version( session, tenant_id=principal.tenant_id, campaign_id=campaign_id, version_id=version_id, current_flow=payload.current_flow, current_step=payload.current_step, autosave=True, commit=False, ), audit_action="campaign.version_step_updated", details={ "campaign_id": campaign_id, "current_flow": payload.current_flow, "current_step": payload.current_step, }, ) @router.post("/{campaign_id}/versions/{version_id}/review-state", response_model=CampaignVersionDetailResponse) def set_version_review_state( campaign_id: str, version_id: str, payload: CampaignReviewStateRequest, session: Session = Depends(get_session), principal: ApiPrincipal = Depends(require_scope("campaigns:campaign:review")), ): _get_campaign_for_principal(session, campaign_id, principal, write=True) try: version = update_campaign_review_state( session, tenant_id=principal.tenant_id, campaign_id=campaign_id, version_id=version_id, inspection_complete=payload.inspection_complete, reviewed_message_keys=payload.reviewed_message_keys, user_id=principal.user.id, commit=False, ) audit_from_principal( session, principal, action="campaign.message_review_updated", object_type="campaign_version", object_id=version.id, details={ "campaign_id": campaign_id, "inspection_complete": payload.inspection_complete, "reviewed_message_count": len(payload.reviewed_message_keys), }, commit=True, ) return CampaignVersionDetailResponse.model_validate( version, context=_campaign_response_context(principal), ) except LockedCampaignVersionError as exc: session.rollback() raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail=str(exc)) from exc except CampaignPersistenceError as exc: session.rollback() raise HTTPException(status_code=status.HTTP_422_UNPROCESSABLE_CONTENT, detail=str(exc)) from exc except Exception: session.rollback() raise @router.post("/{campaign_id}/versions/{version_id}/validate-partial", response_model=CampaignPartialValidationResponse) def validate_version_partial( campaign_id: str, version_id: str, payload: CampaignPartialValidationRequest | None = None, session: Session = Depends(get_session), principal: ApiPrincipal = Depends(require_scope("campaigns:campaign:validate")), ): _get_campaign_for_principal(session, campaign_id, principal, write=True) try: version = get_campaign_version_for_tenant( session, tenant_id=principal.tenant_id, campaign_id=campaign_id, version_id=version_id ) campaign_json = payload.campaign_json if payload and payload.campaign_json is not None else version.raw_json result = validate_campaign_partial(campaign_json, section=payload.section if payload else None) audit_from_principal( session, principal, action="campaign.version_partially_validated", object_type="campaign_version", object_id=version.id, details={"campaign_id": campaign_id, "section": result.get("section"), "ok": result.get("ok")}, commit=True, ) return CampaignPartialValidationResponse(**result) except CampaignPersistenceError as exc: raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=str(exc)) from exc @router.post("/{campaign_id}/versions/{version_id}/publish", response_model=CampaignVersionDetailResponse) def publish_version( campaign_id: str, version_id: str, session: Session = Depends(get_session), principal: ApiPrincipal = Depends(require_scope("campaigns:campaign:update")), ): _get_campaign_for_principal(session, campaign_id, principal, write=True) return _campaign_version_detail_response( session, principal, campaign_id, lambda: publish_campaign_version( session, tenant_id=principal.tenant_id, campaign_id=campaign_id, version_id=version_id, user_id=principal.user.id, commit=False, ), audit_action="campaign.version_user_locked_permanently", ) @router.post("/versions/{version_id}/validate") def validate_version( version_id: str, payload: ValidateCampaignRequest | None = None, session: Session = Depends(get_session), principal: ApiPrincipal = Depends(require_scope("campaigns:campaign:validate")), ): _get_version_for_principal(session, version_id, principal, write=True) _require_permission(principal, "campaigns:recipient:read") payload = payload or ValidateCampaignRequest() try: version = _get_version_for_tenant(session, version_id, principal.tenant_id) _require_mail_profile_use_if_needed(principal, version.raw_json if isinstance(version.raw_json, dict) else {}) if is_user_locked_version(version) or is_version_final_locked(version): raise HTTPException( status_code=status.HTTP_409_CONFLICT, detail="This version has a user lock or final delivery lock and cannot be validated. Remove a temporary lock or create an editable copy.", ) link_result: CampaignAttachmentLinkMatchesResponse | None = None if payload.check_files and payload.link_unshared_matches: _require_permission(principal, "files:file:share") campaign = _get_campaign_for_tenant(session, version.campaign_id, principal.tenant_id) link_result = _link_campaign_attachment_matches( session, principal, campaign=campaign, version=version, raw=version.raw_json if isinstance(version.raw_json, dict) else {}, dry_run=False, ) audit_from_principal( session, principal, action="campaign.attachment_matches_linked", object_type="campaign_version", object_id=version_id, details={ "matched_file_count": link_result.matched_file_count, "already_linked_file_count": link_result.already_linked_file_count, "linked_file_count": link_result.linked_file_count, "during_validation": True, }, commit=True, ) result = validate_campaign_version( session, tenant_id=principal.tenant_id, version_id=version_id, check_files=payload.check_files, user_id=principal.user.id, ) audit_from_principal( session, principal, action="campaign.validated", object_type="campaign_version", object_id=version_id, details={ "check_files": payload.check_files, "link_unshared_matches": payload.link_unshared_matches, "linked_file_count": link_result.linked_file_count if link_result else 0, "ok": result.get("ok"), }, commit=True, ) return public_campaign_payload( result, include_diagnostics=has_scope(principal, "campaigns:diagnostic:read"), ) except HTTPException: raise except CampaignPersistenceError as exc: raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=str(exc)) from exc except Exception as exc: raise HTTPException(status_code=status.HTTP_422_UNPROCESSABLE_CONTENT, detail=str(exc)) from exc @router.post("/versions/{version_id}/build") def build_version( version_id: str, payload: BuildCampaignRequest | None = None, session: Session = Depends(get_session), principal: ApiPrincipal = Depends(require_scope("campaigns:campaign:build")), ): version = _get_version_for_principal(session, version_id, principal, write=True) _require_permission(principal, "campaigns:recipient:read") _require_mail_profile_use_if_needed(principal, version.raw_json if isinstance(version.raw_json, dict) else {}) try: result = build_campaign_version( session, tenant_id=principal.tenant_id, version_id=version_id, write_eml=payload.write_eml if payload else True, ) audit_from_principal( session, principal, action="campaign.messages_built", object_type="campaign_version", object_id=version_id, details={"write_eml": payload.write_eml if payload else True, "built_count": result.get("built_count")}, commit=True, ) return public_campaign_payload( result, include_diagnostics=has_scope(principal, "campaigns:diagnostic:read"), ) except CampaignPersistenceError as exc: raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=str(exc)) from exc except Exception as exc: raise HTTPException(status_code=status.HTTP_422_UNPROCESSABLE_CONTENT, detail=str(exc)) from exc def _job_review_key(job: CampaignJob) -> str: return str(job.entry_id or job.entry_index) def _job_summary_payload( job: CampaignJob, *, reviewed_keys: set[str] | None = None, ) -> dict[str, object]: review_key = _job_review_key(job) return { "id": job.id, "campaign_version_id": job.campaign_version_id, "entry_index": job.entry_index, "entry_id": job.entry_id, "recipient_email": job.recipient_email, "subject": job.subject, "message_id_header": job.message_id_header, "build_status": job.build_status, "validation_status": job.validation_status, "queue_status": job.queue_status, "send_status": job.send_status, "delivery_channel_policy": getattr(job, "delivery_channel_policy", "mail"), "postbox_status": getattr(job, "postbox_status", "not_requested"), "imap_status": job.imap_status, "eml_size_bytes": job.eml_size_bytes, "eml_sha256": job.eml_sha256, "attempt_count": job.attempt_count, "postbox_attempt_count": getattr(job, "postbox_attempt_count", 0), "postbox_target_count": len(getattr(job, "resolved_postbox_targets", None) or []), "last_error": public_delivery_result_message( last_error=job.last_error, send_status=job.send_status, imap_status=job.imap_status, postbox_status=getattr(job, "postbox_status", "not_requested"), ), "queued_at": job.queued_at, "outcome_unknown_at": job.outcome_unknown_at, "sent_at": job.sent_at, "created_at": job.created_at, "updated_at": job.updated_at, "issues_count": len(job.issues_snapshot or []), "attachment_count": len(job.resolved_attachments or []), "review_key": review_key, "reviewed": review_key in reviewed_keys if reviewed_keys is not None else False, "matched_file_count": sum( len(item.get("matches") or []) for item in (job.resolved_attachments or []) if isinstance(item, dict) ), } def _job_detail_payload(job: CampaignJob) -> dict[str, object]: return { **_job_summary_payload(job), "message_id_header": job.message_id_header, "issues": job.issues_snapshot or [], "attachments": public_campaign_payload(job.resolved_attachments or []), "resolved_recipients": job.resolved_recipients or {}, "resolved_postbox_targets": getattr(job, "resolved_postbox_targets", None) or [], } def _job_attempts_payload( send_attempts: list[SendAttempt], imap_attempts: list[ImapAppendAttempt], postbox_attempts: Sequence[PostboxDeliveryAttempt] = (), *, include_diagnostics: bool = False, ) -> dict[str, list[dict[str, object]]]: smtp_payloads: list[dict[str, object]] = [] for attempt in send_attempts: payload: dict[str, object] = { "id": attempt.id, "attempt_number": attempt.attempt_number, "status": attempt.status, "smtp_status_code": attempt.smtp_status_code, "started_at": attempt.started_at, "finished_at": attempt.finished_at, } if include_diagnostics: payload["claim_token"] = attempt.claim_token payload["smtp_response"] = attempt.smtp_response payload["error_type"] = attempt.error_type payload["error_message"] = attempt.error_message smtp_payloads.append(payload) imap_payloads: list[dict[str, object]] = [] for attempt in imap_attempts: payload = { "id": attempt.id, "attempt_number": attempt.attempt_number, "status": attempt.status, "folder": attempt.folder, "created_at": attempt.created_at, "updated_at": attempt.updated_at, } if include_diagnostics: payload["claim_token"] = attempt.claim_token payload["error_message"] = attempt.error_message imap_payloads.append(payload) postbox_payloads: list[dict[str, object]] = [] for attempt in postbox_attempts: payload = { "id": attempt.id, "target_index": attempt.target_index, "attempt_number": attempt.attempt_number, "status": attempt.status, "postbox_id": attempt.postbox_id, "address": attempt.address, "holder_count": attempt.holder_count, "vacant": attempt.vacant, "duplicate": attempt.duplicate, "target": attempt.target_snapshot or {}, "started_at": attempt.started_at, "finished_at": attempt.finished_at, "error_code": attempt.error_code, } if include_diagnostics: payload["idempotency_key"] = attempt.idempotency_key payload["provider_delivery_id"] = attempt.provider_delivery_id payload["provider_message_id"] = attempt.provider_message_id payload["evidence"] = attempt.evidence or {} payload["error_type"] = attempt.error_type payload["error_message"] = attempt.error_message postbox_payloads.append(payload) return { "smtp": smtp_payloads, "imap": imap_payloads, "postbox": postbox_payloads, } def _job_diagnostics_payload( job: CampaignJob, send_attempts: list[SendAttempt], imap_attempts: list[ImapAppendAttempt], postbox_attempts: Sequence[PostboxDeliveryAttempt] = (), ) -> CampaignJobDiagnosticsResponse: return CampaignJobDiagnosticsResponse( job_id=job.id, campaign_id=job.campaign_id, campaign_version_id=job.campaign_version_id, storage={ "eml_local_path": job.eml_local_path, "eml_storage_key": job.eml_storage_key, "eml_size_bytes": job.eml_size_bytes, "eml_sha256": job.eml_sha256, }, worker_claim={ "claim_token": job.claim_token, "claimed_at": job.claimed_at, "smtp_started_at": job.smtp_started_at, "outcome_unknown_at": job.outcome_unknown_at, "last_error": job.last_error, }, attempts=_job_attempts_payload( send_attempts, imap_attempts, postbox_attempts, include_diagnostics=True, ), ) def _review_metadata( session: Session, version: CampaignVersion | None, base_filters: list[object], ) -> tuple[dict[str, object], set[str]]: if version is None: return _empty_review_metadata(), set() review_state, state_is_current = _current_review_state(version) reviewed_keys = _current_reviewed_keys(review_state, state_is_current=state_is_current) counts = _review_metadata_counts(_review_rows(session, base_filters), reviewed_keys) return { "inspection_complete": bool(state_is_current and review_state.get("inspection_complete") is True), **counts, }, reviewed_keys def _empty_review_metadata() -> dict[str, object]: return { "inspection_complete": False, "blocking_count": 0, "required_count": 0, "reviewed_required_count": 0, "bulk_acceptable_count": 0, } def _current_review_state(version: CampaignVersion) -> tuple[dict[str, object], bool]: build_summary = version.build_summary if isinstance(version.build_summary, dict) else {} build_token = str(build_summary.get("build_token") or build_summary.get("built_at") or "") editor_state = version.editor_state if isinstance(version.editor_state, dict) else {} review_state = editor_state.get("review_send") if isinstance(editor_state.get("review_send"), dict) else {} state_token = str(review_state.get("build_token") or "") return review_state, bool(build_token and state_token == build_token) def _current_reviewed_keys(review_state: dict[str, object], *, state_is_current: bool) -> set[str]: return { str(value) for value in (review_state.get("reviewed_message_keys") or []) if state_is_current and str(value).strip() } def _review_rows(session: Session, base_filters: list[object]) -> list[tuple[object, int, str, str]]: return ( session.query( CampaignJob.entry_id, CampaignJob.entry_index, CampaignJob.build_status, CampaignJob.validation_status, ) .filter(*base_filters) .all() ) def _review_metadata_counts(review_rows: list[tuple[object, int, str, str]], reviewed_keys: set[str]) -> dict[str, int]: blocking_count = 0 required_count = 0 reviewed_required_count = 0 bulk_acceptable_count = 0 for entry_id, entry_index, build_status, validation_status in review_rows: key = str(entry_id or entry_index) if build_status != "built" or validation_status == "blocked": blocking_count += 1 if validation_status == "needs_review": required_count += 1 if key in reviewed_keys: reviewed_required_count += 1 elif validation_status in {"warning", "excluded"}: bulk_acceptable_count += 1 return { "blocking_count": blocking_count, "required_count": required_count, "reviewed_required_count": reviewed_required_count, "bulk_acceptable_count": bulk_acceptable_count, } def _status_counts(session: Session, filters: list[object]) -> dict[str, dict[str, int]]: result: dict[str, dict[str, int]] = {} for field_name in ( "build_status", "validation_status", "queue_status", "send_status", "postbox_status", "imap_status", ): column = getattr(CampaignJob, field_name) rows = session.query(column, func.count(CampaignJob.id)).filter(*filters).group_by(column).all() result[field_name.removesuffix("_status")] = {str(value or "unknown"): int(count) for value, count in rows} return result CAMPAIGN_JOB_GRID_SORT_COLUMNS = { "number": CampaignJob.entry_index, "recipient": func.lower(func.coalesce(CampaignJob.recipient_email, "")), "subject": func.lower(func.coalesce(CampaignJob.subject, "")), "validation": CampaignJob.validation_status, "queue": CampaignJob.queue_status, "send": CampaignJob.send_status, "postbox": CampaignJob.postbox_status, "imap": CampaignJob.imap_status, "attempts": CampaignJob.attempt_count, "updated": CampaignJob.updated_at, } CAMPAIGN_JOB_GRID_LIST_FILTERS = { "validation": (CampaignJob.validation_status, {item.value for item in JobValidationStatus}), "queue": (CampaignJob.queue_status, {item.value for item in JobQueueStatus}), "send": (CampaignJob.send_status, {item.value for item in JobSendStatus}), "postbox": ( CampaignJob.postbox_status, {item.value for item in JobPostboxStatus}, ), "imap": (CampaignJob.imap_status, {item.value for item in JobImapStatus}), } def _campaign_jobs_grid_filter_expressions(grid_filters: dict[str, str] | None) -> list[object]: values = grid_filters or {} expressions: list[object] = [] recipient = values.get("recipient", "").strip() if recipient: pattern = _contains_pattern(recipient) expressions.append(or_( CampaignJob.recipient_email.ilike(pattern, escape="\\"), CampaignJob.entry_id.ilike(pattern, escape="\\"), )) subject = values.get("subject", "").strip() if subject: expressions.append(CampaignJob.subject.ilike(_contains_pattern(subject), escape="\\")) evidence = values.get("evidence", "").strip() if evidence: pattern = _contains_pattern(evidence) expressions.append(or_( CampaignJob.message_id_header.ilike(pattern, escape="\\"), CampaignJob.eml_sha256.ilike(pattern, escape="\\"), )) attempts = values.get("attempts", "").strip() if attempts: expressions.append(_campaign_jobs_integer_filter(CampaignJob.attempt_count, attempts, column_id="attempts")) for column_id, (column, allowed_values) in CAMPAIGN_JOB_GRID_LIST_FILTERS.items(): raw_value = values.get(column_id, "").strip() if not raw_value: continue selected = _campaign_jobs_list_filter(raw_value, column_id=column_id, allowed_values=allowed_values) expressions.append(column.in_(selected)) return expressions def _campaign_jobs_list_filter(raw_value: str, *, column_id: str, allowed_values: set[str]) -> list[str]: if raw_value.startswith("list:"): try: parsed = json.loads(raw_value[5:]) except json.JSONDecodeError as exc: raise HTTPException( status_code=status.HTTP_422_UNPROCESSABLE_CONTENT, detail=f"Invalid {column_id} list filter", ) from exc if not isinstance(parsed, list) or any(not isinstance(value, str) for value in parsed): raise HTTPException( status_code=status.HTTP_422_UNPROCESSABLE_CONTENT, detail=f"Invalid {column_id} list filter", ) selected = list(dict.fromkeys(value.strip() for value in parsed if value.strip())) else: selected = list(dict.fromkeys(value.strip() for value in raw_value.split(",") if value.strip())) if len(selected) > 50 or any(value not in allowed_values for value in selected): raise HTTPException( status_code=status.HTTP_422_UNPROCESSABLE_CONTENT, detail=f"Invalid {column_id} list filter", ) return selected def _campaign_jobs_integer_filter(column: object, raw_value: str, *, column_id: str): operator, separator, value = raw_value.partition(":") if not separator: operator, value = "eq", operator if operator not in {"eq", "gt", "gte", "lt", "lte"}: raise HTTPException( status_code=status.HTTP_422_UNPROCESSABLE_CONTENT, detail=f"Invalid {column_id} filter operator", ) try: expected = int(value) except ValueError as exc: raise HTTPException( status_code=status.HTTP_422_UNPROCESSABLE_CONTENT, detail=f"Invalid {column_id} filter value", ) from exc if operator == "gt": return column > expected if operator == "gte": return column >= expected if operator == "lt": return column < expected if operator == "lte": return column <= expected return column == expected def _contains_pattern(value: str) -> str: escaped = value.replace("\\", "\\\\").replace("%", "\\%").replace("_", "\\_") return f"%{escaped}%" def _campaign_jobs_ordering(sort_by: str, sort_direction: str) -> list[object]: column = CAMPAIGN_JOB_GRID_SORT_COLUMNS.get(sort_by) if column is None: raise HTTPException( status_code=status.HTTP_422_UNPROCESSABLE_CONTENT, detail="Unsupported Campaign job sort column", ) primary = column.desc() if sort_direction == "desc" else column.asc() return [primary, CampaignJob.id.asc()] def _campaign_jobs_query_context( session: Session, principal: ApiPrincipal, *, campaign_id: str, version_id: str | None, send_status: list[str] | None, validation_status: list[str] | None, imap_status: list[str] | None, query_text: str | None, grid_filters: dict[str, str] | None = None, ) -> tuple[Campaign, list[object], list[object], dict[str, object], set[str]]: _get_campaign_for_principal(session, campaign_id, principal) _require_permission(principal, "campaigns:recipient:read") campaign = _get_campaign_for_tenant(session, campaign_id, principal.tenant_id) base_filters: list[object] = [CampaignJob.campaign_id == campaign.id, CampaignJob.tenant_id == principal.tenant_id] selected_version: CampaignVersion | None = None if version_id: version = _get_version_for_tenant(session, version_id, principal.tenant_id) if version.campaign_id != campaign.id: raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Campaign version not found") selected_version = version base_filters.append(CampaignJob.campaign_version_id == version.id) review_metadata, reviewed_keys = _review_metadata(session, selected_version, base_filters) filtered = list(base_filters) if send_status: filtered.append(CampaignJob.send_status.in_(send_status)) if validation_status: filtered.append(CampaignJob.validation_status.in_(validation_status)) if imap_status: filtered.append(CampaignJob.imap_status.in_(imap_status)) if query_text and query_text.strip(): pattern = f"%{query_text.strip()}%" filtered.append(or_( CampaignJob.recipient_email.ilike(pattern), CampaignJob.subject.ilike(pattern), CampaignJob.entry_id.ilike(pattern), )) filtered.extend(_campaign_jobs_grid_filter_expressions(grid_filters)) return campaign, base_filters, filtered, review_metadata, reviewed_keys def _campaign_jobs_page_response( session: Session, *, campaign_id: str, version_id: str | None, base_filters: list[object], filtered: list[object], reviewed_keys: set[str], review_metadata: dict[str, object], page: int, page_size: int, send_status: list[str] | None = None, validation_status: list[str] | None = None, imap_status: list[str] | None = None, query_text: str | None = None, grid_filters: dict[str, str] | None = None, sort_by: str = "number", sort_direction: str = "asc", cursor: str | None = None, changed_job_ids: set[str] | None = None, ) -> CampaignJobsResponse: total_unfiltered = int(session.query(func.count(CampaignJob.id)).filter(*base_filters).scalar() or 0) total = int(session.query(func.count(CampaignJob.id)).filter(*filtered).scalar() or 0) pages = (total + page_size - 1) // page_size if total else 0 fingerprint = _campaign_jobs_cursor_fingerprint( campaign_id=campaign_id, version_id=version_id, page_size=page_size, send_status=send_status, validation_status=validation_status, imap_status=imap_status, query_text=query_text, grid_filters=grid_filters, sort_by=sort_by, sort_direction=sort_direction, ) ordering = _campaign_jobs_ordering(sort_by, sort_direction) ordered_query = session.query(CampaignJob).filter(*filtered).order_by(*ordering) start_cursor: str | None = None effective_offset = 0 if cursor: if sort_by != "number" or sort_direction != "asc": raise HTTPException( status_code=status.HTTP_400_BAD_REQUEST, detail="Campaign job cursors require number ascending order", ) try: cursor_values = decode_keyset_cursor(CAMPAIGN_JOBS_CURSOR_SCOPE, cursor, fingerprint=fingerprint) if cursor_values is None: raise KeysetCursorError("Invalid pagination cursor") page_query = session.query(CampaignJob).filter(*filtered).filter(_campaign_jobs_cursor_condition(cursor_values)) except KeysetCursorError as exc: raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(exc)) from exc start_cursor = cursor else: effective_offset = (page - 1) * page_size page_query = session.query(CampaignJob).filter(*filtered) if effective_offset > 0 and sort_by == "number" and sort_direction == "asc": previous_row = ordered_query.offset(effective_offset - 1).limit(1).first() if previous_row is not None: start_cursor = _campaign_jobs_cursor_for_row(previous_row, fingerprint=fingerprint) rows_plus_one = ( page_query .order_by(*ordering) .offset(effective_offset) .limit(page_size + 1) .all() ) jobs = rows_plus_one[:page_size] next_cursor = ( _campaign_jobs_cursor_for_row(jobs[-1], fingerprint=fingerprint) if changed_job_ids is None and sort_by == "number" and sort_direction == "asc" and len(rows_plus_one) > page_size and jobs else None ) if changed_job_ids is not None: jobs = [job for job in jobs if job.id in changed_job_ids] return CampaignJobsResponse( jobs=[_job_summary_payload(job, reviewed_keys=reviewed_keys) for job in jobs], page=page, page_size=page_size, total=total, total_unfiltered=total_unfiltered, pages=pages, cursor=start_cursor, next_cursor=next_cursor, counts=_status_counts(session, base_filters), filtered_counts=_status_counts(session, filtered), review=review_metadata, ) def _campaign_jobs_cursor_fingerprint( *, campaign_id: str, version_id: str | None, page_size: int, send_status: list[str] | None, validation_status: list[str] | None, imap_status: list[str] | None, query_text: str | None, grid_filters: dict[str, str] | None, sort_by: str, sort_direction: str, ) -> str: return keyset_query_fingerprint( CAMPAIGN_JOBS_CURSOR_SCOPE, { "campaign_id": campaign_id, "version_id": version_id or "", "page_size": page_size, "send_status": sorted(send_status or []), "validation_status": sorted(validation_status or []), "imap_status": sorted(imap_status or []), "query": (query_text or "").strip(), "grid_filters": sorted((grid_filters or {}).items()), "order": [f"{sort_by}:{sort_direction}", "id:asc"], }, ) def _campaign_jobs_cursor_for_row(row: CampaignJob, *, fingerprint: str) -> str: return encode_keyset_cursor( CAMPAIGN_JOBS_CURSOR_SCOPE, fingerprint=fingerprint, values={"id": row.id, "entry_index": row.entry_index}, ) def _campaign_jobs_cursor_condition(cursor_values: dict[str, object]): cursor_id = cursor_values.get("id") cursor_index = cursor_values.get("entry_index") if not isinstance(cursor_id, str) or not cursor_id: raise KeysetCursorError("Invalid pagination cursor") try: entry_index = int(cursor_index) except (TypeError, ValueError) as exc: raise KeysetCursorError("Invalid pagination cursor") from exc return or_(CampaignJob.entry_index > entry_index, and_(CampaignJob.entry_index == entry_index, CampaignJob.id > cursor_id)) def _campaign_jobs_delta_watermark(session: Session, tenant_id: str) -> str: return encode_sequence_watermark( max_sequence_id( session, tenant_id=tenant_id, module_id=CAMPAIGNS_MODULE_ID, collections=(CAMPAIGN_JOBS_COLLECTION,), ) ) class CampaignJobsQuery: def __init__( self, version_id: str | None = None, page: int = Query(default=1, ge=1), page_size: int = Query(default=50, ge=1, le=200), cursor: str | None = Query(default=None), send_status: list[str] | None = Query(default=None), validation_status: list[str] | None = Query(default=None), imap_status: list[str] | None = Query(default=None), query_text: str | None = Query(default=None, alias="q", max_length=200), sort_by: Literal["number", "recipient", "subject", "validation", "queue", "send", "postbox", "imap", "attempts", "updated"] = Query(default="number"), sort_direction: Literal["asc", "desc"] = Query(default="asc"), filter_recipient: str | None = Query(default=None, max_length=500), filter_subject: str | None = Query(default=None, max_length=1000), filter_validation: str | None = Query(default=None, max_length=1000), filter_queue: str | None = Query(default=None, max_length=1000), filter_send: str | None = Query(default=None, max_length=1000), filter_postbox: str | None = Query(default=None, max_length=1000), filter_imap: str | None = Query(default=None, max_length=1000), filter_attempts: str | None = Query(default=None, max_length=100), filter_evidence: str | None = Query(default=None, max_length=500), ) -> None: self.version_id = version_id self.page = page self.page_size = page_size self.cursor = cursor self.send_status = send_status self.validation_status = validation_status self.imap_status = imap_status self.query_text = query_text self.sort_by = sort_by self.sort_direction = sort_direction self.grid_filters = { column_id: value for column_id, value in { "recipient": filter_recipient, "subject": filter_subject, "validation": filter_validation, "queue": filter_queue, "send": filter_send, "postbox": filter_postbox, "imap": filter_imap, "attempts": filter_attempts, "evidence": filter_evidence, }.items() if value is not None and value.strip() } @router.get("/{campaign_id}/jobs", response_model=CampaignJobsResponse) def list_jobs( campaign_id: str, filters: CampaignJobsQuery = Depends(CampaignJobsQuery), session: Session = Depends(get_session), principal: ApiPrincipal = Depends(require_scope("campaigns:campaign:read")), ): """Return a lightweight, paginated job list with server-side filters. Complete recipients, attachment metadata, issues and attempt history are available from the separate job-detail endpoint. """ _campaign, base_filters, filtered, review_metadata, reviewed_keys = _campaign_jobs_query_context( session, principal, campaign_id=campaign_id, version_id=filters.version_id, send_status=filters.send_status, validation_status=filters.validation_status, imap_status=filters.imap_status, query_text=filters.query_text, grid_filters=filters.grid_filters, ) return _campaign_jobs_page_response( session, campaign_id=campaign_id, version_id=filters.version_id, base_filters=base_filters, filtered=filtered, reviewed_keys=reviewed_keys, review_metadata=review_metadata, page=filters.page, page_size=filters.page_size, send_status=filters.send_status, validation_status=filters.validation_status, imap_status=filters.imap_status, query_text=filters.query_text, grid_filters=filters.grid_filters, sort_by=filters.sort_by, sort_direction=filters.sort_direction, cursor=filters.cursor, ) def _campaign_jobs_full_delta_response( session: Session, *, principal: ApiPrincipal, campaign_id: str, version_id: str | None, page: int, page_size: int, send_status: list[str] | None, validation_status: list[str] | None, imap_status: list[str] | None, query_text: str | None, grid_filters: dict[str, str] | None, sort_by: str, sort_direction: str, cursor: str | None = None, ) -> CampaignJobsDeltaResponse: _campaign, base_filters, filtered, review_metadata, reviewed_keys = _campaign_jobs_query_context( session, principal, campaign_id=campaign_id, version_id=version_id, send_status=send_status, validation_status=validation_status, imap_status=imap_status, query_text=query_text, grid_filters=grid_filters, ) payload = _campaign_jobs_page_response( session, campaign_id=campaign_id, version_id=version_id, base_filters=base_filters, filtered=filtered, reviewed_keys=reviewed_keys, review_metadata=review_metadata, page=page, page_size=page_size, send_status=send_status, validation_status=validation_status, imap_status=imap_status, query_text=query_text, grid_filters=grid_filters, sort_by=sort_by, sort_direction=sort_direction, cursor=cursor, ) return CampaignJobsDeltaResponse( **payload.model_dump(), deleted=[], watermark=_campaign_jobs_delta_watermark(session, principal.tenant_id), has_more=False, full=True, ) def _job_filter_membership_can_shift( *, send_status: list[str] | None, validation_status: list[str] | None, imap_status: list[str] | None, query_text: str | None, grid_filters: dict[str, str] | None, sort_by: str, sort_direction: str, ) -> bool: return bool( send_status or validation_status or imap_status or (query_text and query_text.strip()) or grid_filters or sort_by != "number" or sort_direction != "asc" ) @router.get("/{campaign_id}/jobs/delta", response_model=CampaignJobsDeltaResponse) def list_jobs_delta( campaign_id: str, filters: CampaignJobsQuery = Depends(CampaignJobsQuery), since: str | None = None, limit: int = Query(default=500, ge=1, le=1000), session: Session = Depends(get_session), principal: ApiPrincipal = Depends(require_scope("campaigns:campaign:read")), ): if since is None: return _campaign_jobs_full_delta_response( session, principal=principal, campaign_id=campaign_id, version_id=filters.version_id, page=filters.page, page_size=filters.page_size, send_status=filters.send_status, validation_status=filters.validation_status, imap_status=filters.imap_status, query_text=filters.query_text, grid_filters=filters.grid_filters, sort_by=filters.sort_by, sort_direction=filters.sort_direction, cursor=filters.cursor, ) campaign, base_filters, filtered, review_metadata, reviewed_keys = _campaign_jobs_query_context( session, principal, campaign_id=campaign_id, version_id=filters.version_id, send_status=filters.send_status, validation_status=filters.validation_status, imap_status=filters.imap_status, query_text=filters.query_text, grid_filters=filters.grid_filters, ) try: since_sequence = decode_sequence_watermark(since) except ValueError as exc: raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(exc)) from exc if sequence_watermark_is_expired( session, since=since_sequence, tenant_id=principal.tenant_id, module_id=CAMPAIGNS_MODULE_ID, collections=(CAMPAIGN_JOBS_COLLECTION,), ): return _campaign_jobs_full_delta_response( session, principal=principal, campaign_id=campaign_id, version_id=filters.version_id, page=filters.page, page_size=filters.page_size, send_status=filters.send_status, validation_status=filters.validation_status, imap_status=filters.imap_status, query_text=filters.query_text, grid_filters=filters.grid_filters, sort_by=filters.sort_by, sort_direction=filters.sort_direction, cursor=filters.cursor, ) entries_plus_one = sequence_entries_since( session, since=since_sequence, tenant_id=principal.tenant_id, module_id=CAMPAIGNS_MODULE_ID, collections=(CAMPAIGN_JOBS_COLLECTION,), limit=limit + 1, ) has_more = len(entries_plus_one) > limit entries = entries_plus_one[:limit] relevant_entries = [ entry for entry in entries if (entry.payload or {}).get("campaign_id") == campaign.id and (not filters.version_id or (entry.payload or {}).get("version_id") == filters.version_id) ] if relevant_entries and ( _job_filter_membership_can_shift( send_status=filters.send_status, validation_status=filters.validation_status, imap_status=filters.imap_status, query_text=filters.query_text, grid_filters=filters.grid_filters, sort_by=filters.sort_by, sort_direction=filters.sort_direction, ) or any(entry.operation in {"created", "deleted"} for entry in relevant_entries) ): return _campaign_jobs_full_delta_response( session, principal=principal, campaign_id=campaign_id, version_id=filters.version_id, page=filters.page, page_size=filters.page_size, send_status=filters.send_status, validation_status=filters.validation_status, imap_status=filters.imap_status, query_text=filters.query_text, grid_filters=filters.grid_filters, sort_by=filters.sort_by, sort_direction=filters.sort_direction, cursor=filters.cursor, ) changed_job_ids = { entry.resource_id for entry in relevant_entries if entry.resource_type == "campaign_job" and entry.operation != "deleted" } payload = _campaign_jobs_page_response( session, campaign_id=campaign_id, version_id=filters.version_id, base_filters=base_filters, filtered=filtered, reviewed_keys=reviewed_keys, review_metadata=review_metadata, page=filters.page, page_size=filters.page_size, send_status=filters.send_status, validation_status=filters.validation_status, imap_status=filters.imap_status, query_text=filters.query_text, grid_filters=filters.grid_filters, sort_by=filters.sort_by, sort_direction=filters.sort_direction, cursor=filters.cursor, changed_job_ids=changed_job_ids, ) watermark = ( encode_sequence_watermark(entries[-1].id) if has_more and entries else _campaign_jobs_delta_watermark(session, principal.tenant_id) ) return CampaignJobsDeltaResponse( **payload.model_dump(), deleted=[], watermark=watermark, has_more=has_more, full=False, ) @router.get("/{campaign_id}/jobs/{job_id}", response_model=CampaignJobDetailResponse) def get_job_detail( campaign_id: str, job_id: str, session: Session = Depends(get_session), principal: ApiPrincipal = Depends(require_scope("campaigns:campaign:read")), ): _get_campaign_for_principal(session, campaign_id, principal) _require_permission(principal, "campaigns:recipient:read") campaign = _get_campaign_for_tenant(session, campaign_id, principal.tenant_id) job = session.get(CampaignJob, job_id) if not job or job.campaign_id != campaign.id or job.tenant_id != principal.tenant_id: raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Campaign job not found") send_attempts = _job_attempt_rows( session.query(SendAttempt) .filter(SendAttempt.job_id == job.id) .order_by(SendAttempt.attempt_number.asc()), label="SMTP attempts for this campaign job", ) imap_attempts = _job_attempt_rows( session.query(ImapAppendAttempt) .filter(ImapAppendAttempt.job_id == job.id) .order_by(ImapAppendAttempt.attempt_number.asc()), label="IMAP attempts for this campaign job", ) postbox_attempts = _job_attempt_rows( session.query(PostboxDeliveryAttempt) .filter(PostboxDeliveryAttempt.job_id == job.id) .order_by( PostboxDeliveryAttempt.target_index.asc(), PostboxDeliveryAttempt.attempt_number.asc(), ), label="Postbox attempts for this campaign job", ) return CampaignJobDetailResponse( job=_job_detail_payload(job), attempts=_job_attempts_payload( send_attempts, imap_attempts, postbox_attempts, ), ) @router.get( "/{campaign_id}/jobs/{job_id}/diagnostics", response_model=CampaignJobDiagnosticsResponse, ) def get_job_diagnostics( campaign_id: str, job_id: str, session: Session = Depends(get_session), principal: ApiPrincipal = Depends(require_scope("campaigns:diagnostic:read")), ): """Return infrastructure details only to campaign operators/admins.""" _get_campaign_for_principal(session, campaign_id, principal) _require_permission(principal, "campaigns:recipient:read") campaign = _get_campaign_for_tenant(session, campaign_id, principal.tenant_id) job = session.get(CampaignJob, job_id) if not job or job.campaign_id != campaign.id or job.tenant_id != principal.tenant_id: raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Campaign job not found") send_attempts = _job_attempt_rows( session.query(SendAttempt) .filter(SendAttempt.job_id == job.id) .order_by(SendAttempt.attempt_number.asc()), label="SMTP diagnostics for this campaign job", ) imap_attempts = _job_attempt_rows( session.query(ImapAppendAttempt) .filter(ImapAppendAttempt.job_id == job.id) .order_by(ImapAppendAttempt.attempt_number.asc()), label="IMAP diagnostics for this campaign job", ) postbox_attempts = _job_attempt_rows( session.query(PostboxDeliveryAttempt) .filter(PostboxDeliveryAttempt.job_id == job.id) .order_by( PostboxDeliveryAttempt.target_index.asc(), PostboxDeliveryAttempt.attempt_number.asc(), ), label="Postbox diagnostics for this campaign job", ) return _job_diagnostics_payload( job, send_attempts, imap_attempts, postbox_attempts, ) @router.get("/{campaign_id}/summary") def campaign_summary( campaign_id: str, version_id: str | None = None, include_jobs: bool = False, session: Session = Depends(get_session), principal: ApiPrincipal = Depends(require_scope("campaigns:campaign:read")), ): """Return dashboard-friendly campaign status counters and summaries.""" _get_campaign_for_principal(session, campaign_id, principal) if include_jobs: _require_permission(principal, "campaigns:recipient:read") try: return generate_campaign_report( session, tenant_id=principal.tenant_id, campaign_id=campaign_id, version_id=version_id, include_jobs=include_jobs, include_recent_failures=include_jobs, include_diagnostics=has_scope(principal, "campaigns:diagnostic:read"), ) except CampaignReportError as exc: raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=str(exc)) from exc @router.get("/{campaign_id}/report") def campaign_report( campaign_id: str, version_id: str | None = None, include_jobs: bool = False, session: Session = Depends(get_session), principal: ApiPrincipal = Depends(require_scope("campaigns:report:read")), ): """Return the recipient-level JSON report for one campaign.""" _get_campaign_for_principal(session, campaign_id, principal) _require_permission(principal, "campaigns:recipient:read") try: return generate_campaign_report( session, tenant_id=principal.tenant_id, campaign_id=campaign_id, version_id=version_id, include_jobs=include_jobs, include_recent_failures=include_jobs, include_diagnostics=has_scope(principal, "campaigns:diagnostic:read"), ) except CampaignReportError as exc: raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=str(exc)) from exc @router.get("/{campaign_id}/report/jobs.csv") def campaign_jobs_csv( campaign_id: str, version_id: str | None = None, session: Session = Depends(get_session), principal: ApiPrincipal = Depends(require_scope("campaigns:report:export")), ): """Export per-job campaign status as CSV.""" _get_campaign_for_principal(session, campaign_id, principal) _require_permission(principal, "campaigns:recipient:export") try: csv_text = generate_jobs_csv( session, tenant_id=principal.tenant_id, campaign_id=campaign_id, version_id=version_id, include_diagnostics=has_scope(principal, "campaigns:diagnostic:read"), ) except CampaignReportError as exc: raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=str(exc)) from exc return Response( content=csv_text, media_type="text/csv; charset=utf-8", headers={"Content-Disposition": f'attachment; filename="campaign-{campaign_id}-jobs.csv"'}, ) @router.post("/{campaign_id}/report/email", response_model=ReportEmailResponse) def email_campaign_report( campaign_id: str, payload: ReportEmailRequest, session: Session = Depends(get_session), principal: ApiPrincipal = Depends(require_scope("campaigns:report:send")), ): """Generate a campaign report and send it to one or more email addresses.""" campaign = _get_campaign_for_principal(session, campaign_id, principal) _require_permission(principal, "campaigns:recipient:export") selected_version_id = payload.version_id or campaign.current_version_id selected_version = session.get(CampaignVersion, selected_version_id) if selected_version_id else None if selected_version is not None and selected_version.campaign_id == campaign.id: _require_mail_profile_use_if_needed( principal, selected_version.raw_json if isinstance(selected_version.raw_json, dict) else {}, ) try: result = send_campaign_report_email( session, tenant_id=principal.tenant_id, campaign_id=campaign_id, version_id=payload.version_id, to=payload.to, include_jobs=payload.include_jobs, attach_jobs_csv=payload.attach_jobs_csv, attach_report_json=payload.attach_report_json, dry_run=payload.dry_run, ) audit_from_principal( session, principal, action="report.email_sent" if not payload.dry_run else "report.email_dry_run", object_type="campaign", object_id=campaign_id, details=result.as_dict(), commit=True, ) return ReportEmailResponse(result=result.as_dict()) except CampaignReportError as exc: raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=str(exc)) from exc except (CampaignReportEmailError, MailProfileError, SmtpConfigurationError, SmtpSendError) as exc: raise HTTPException(status_code=status.HTTP_422_UNPROCESSABLE_CONTENT, detail=str(exc)) from exc except Exception as exc: logger.error("Campaign report email failed with an unexpected internal error") raise HTTPException( status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail="Campaign report email could not be completed.", ) from exc @router.get("/{campaign_id}/share-targets", response_model=CampaignShareTargetsResponse) def list_campaign_share_targets( campaign_id: str, limit: int = Query(default=500, ge=1, le=1000), session: Session = Depends(get_session), principal: ApiPrincipal = Depends(require_scope("campaigns:campaign:share")), ): _get_campaign_for_principal(session, campaign_id, principal, write=True) directory = _access_directory() users = [user for user in directory.users_for_tenant(principal.tenant_id) if user.status == "active"] groups = [group for group in directory.groups_for_tenant(principal.tenant_id) if group.status == "active"] if len(users) > limit or len(groups) > limit: raise HTTPException( status_code=status.HTTP_413_CONTENT_TOO_LARGE, detail=( f"Campaign share targets exceed the maximum response size of {limit} " "users or groups. Use a searchable directory selector." ), ) return CampaignShareTargetsResponse( users=[CampaignShareTargetItem(id=item.id, name=item.display_name or item.email, secondary=item.email) for item in users], groups=[CampaignShareTargetItem(id=item.id, name=item.name, secondary=None) for item in groups], ) @router.get("/{campaign_id}/shares", response_model=CampaignShareListResponse) def list_campaign_shares( campaign_id: str, page: int = Query(default=1, ge=1), page_size: int = Query(default=500, ge=1, le=1000), session: Session = Depends(get_session), principal: ApiPrincipal = Depends(require_scope("campaigns:campaign:share")), ): campaign = _get_campaign_for_principal(session, campaign_id, principal, write=True) query = ( session.query(CampaignShare) .filter(CampaignShare.tenant_id == principal.tenant_id, CampaignShare.campaign_id == campaign.id, CampaignShare.revoked_at.is_(None)) ) total = query.order_by(None).count() pages = max(1, (total + page_size - 1) // page_size) shares = ( query.order_by( CampaignShare.target_type.asc(), CampaignShare.target_id.asc(), CampaignShare.id.asc(), ) .offset((page - 1) * page_size) .limit(page_size) .all() ) return CampaignShareListResponse( shares=[CampaignShareItem.model_validate(item) for item in shares], total=total, page=page, page_size=page_size, pages=pages, ) @router.put("/{campaign_id}/owner", response_model=CampaignResponse) def update_campaign_owner( campaign_id: str, payload: CampaignOwnerUpdateRequest, session: Session = Depends(get_session), principal: ApiPrincipal = Depends(require_scope("campaigns:campaign:share")), ): campaign = _get_campaign_for_principal(session, campaign_id, principal, write=True) if payload.owner_user_id and payload.owner_group_id: raise HTTPException(status_code=status.HTTP_422_UNPROCESSABLE_CONTENT, detail="Choose either a user owner or a group owner, not both") directory = _access_directory() if payload.owner_user_id: owner = directory.get_user(payload.owner_user_id) if owner is not None and (owner.tenant_id != principal.tenant_id or owner.status != "active"): owner = None if owner is None: raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Owner user not found") if payload.owner_group_id: group = directory.get_group(payload.owner_group_id) if group is not None and (group.tenant_id != principal.tenant_id or group.status != "active"): group = None if group is None: raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Owner group not found") owner_changed = campaign.owner_user_id != payload.owner_user_id or campaign.owner_group_id != payload.owner_group_id mail_profile_reselection_required = False if owner_changed: mail_profile_reselection_required = _clear_current_version_mail_profile_for_owner_transfer(session, campaign) campaign.owner_user_id = payload.owner_user_id campaign.owner_group_id = payload.owner_group_id session.add(campaign) audit_from_principal( session, principal, action="campaign.owner_updated", object_type="campaign", object_id=campaign.id, details={**payload.model_dump(), "mail_profile_reselection_required": mail_profile_reselection_required}, commit=True, ) return CampaignResponse.model_validate(campaign) @router.post("/{campaign_id}/shares", response_model=CampaignShareItem, status_code=status.HTTP_201_CREATED) def upsert_campaign_share( campaign_id: str, payload: CampaignShareUpsertRequest, session: Session = Depends(get_session), principal: ApiPrincipal = Depends(require_scope("campaigns:campaign:share")), ): campaign = _get_campaign_for_principal(session, campaign_id, principal, write=True) directory = _access_directory() if payload.target_type == "user": target = directory.get_user(payload.target_id) if target is not None and (target.tenant_id != principal.tenant_id or target.status != "active"): target = None else: target = directory.get_group(payload.target_id) if target is not None and (target.tenant_id != principal.tenant_id or target.status != "active"): target = None if target is None: raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Share target not found") share = ( session.query(CampaignShare) .filter(CampaignShare.campaign_id == campaign.id, CampaignShare.target_type == payload.target_type, CampaignShare.target_id == payload.target_id) .one_or_none() ) if share is None: share = CampaignShare( tenant_id=principal.tenant_id, campaign_id=campaign.id, target_type=payload.target_type, target_id=payload.target_id, permission=payload.permission, created_by_user_id=principal.user.id, ) else: share.permission = payload.permission share.revoked_at = None session.add(share) audit_from_principal(session, principal, action="campaign.share_upserted", object_type="campaign", object_id=campaign.id, details=payload.model_dump(), commit=True) return CampaignShareItem.model_validate(share) @router.delete("/{campaign_id}/shares/{share_id}", status_code=status.HTTP_204_NO_CONTENT) def revoke_campaign_share( campaign_id: str, share_id: str, session: Session = Depends(get_session), principal: ApiPrincipal = Depends(require_scope("campaigns:campaign:share")), ): campaign = _get_campaign_for_principal(session, campaign_id, principal, write=True) share = session.query(CampaignShare).filter(CampaignShare.id == share_id, CampaignShare.campaign_id == campaign.id, CampaignShare.tenant_id == principal.tenant_id).one_or_none() if share is None: raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Campaign share not found") share.revoked_at = utc_now() session.add(share) audit_from_principal(session, principal, action="campaign.share_revoked", object_type="campaign", object_id=campaign.id, details={"share_id": share_id}, commit=True) return None # Queue / delivery control ------------------------------------------------- @router.get("/{campaign_id}/delivery-options", response_model=CampaignDeliveryOptionsResponse) def campaign_delivery_options( campaign_id: str, version_id: str | None = None, session: Session = Depends(get_session), principal: ApiPrincipal = Depends( require_any_scope("campaigns:campaign:send", "campaigns:campaign:queue") ), ): _get_campaign_for_principal(session, campaign_id, principal, write=True) _require_permission(principal, "campaigns:recipient:read") try: return CampaignDeliveryOptionsResponse( **synchronous_send_options( session, tenant_id=principal.tenant_id, campaign_id=campaign_id, version_id=version_id, ), postbox_available=postbox_integration().available, ) except QueueingError as exc: raise HTTPException(status_code=status.HTTP_422_UNPROCESSABLE_CONTENT, detail=str(exc)) from exc @router.post("/{campaign_id}/queue", response_model=QueueCampaignResponse) def queue_campaign( campaign_id: str, payload: QueueCampaignRequest | None = None, session: Session = Depends(get_session), principal: ApiPrincipal = Depends(require_scope("campaigns:campaign:queue")), ): _get_campaign_for_principal(session, campaign_id, principal, write=True) _require_permission(principal, "campaigns:recipient:read") payload = payload or QueueCampaignRequest() _require_campaign_profile_use_if_needed(session, principal, campaign_id, payload.version_id) try: result = queue_campaign_jobs( session, tenant_id=principal.tenant_id, campaign_id=campaign_id, version_id=payload.version_id, include_warnings=payload.include_warnings, enqueue_celery=payload.enqueue_celery, dry_run=payload.dry_run, ) audit_from_principal( session, principal, action="campaign.queued" if not payload.dry_run else "campaign.queue_dry_run", object_type="campaign", object_id=campaign_id, details=result.as_dict(), commit=True, ) return QueueCampaignResponse(**result.as_dict()) except QueueingError as exc: raise HTTPException(status_code=status.HTTP_422_UNPROCESSABLE_CONTENT, detail=str(exc)) from exc @router.post("/{campaign_id}/jobs/retry", response_model=CampaignActionResponse) def retry_campaign_jobs( campaign_id: str, payload: CampaignRetryJobsRequest | None = None, session: Session = Depends(get_session), principal: ApiPrincipal = Depends(require_scope("campaigns:campaign:retry")), ): _get_campaign_for_principal(session, campaign_id, principal, write=True) _require_permission(principal, "campaigns:recipient:read") payload = payload or CampaignRetryJobsRequest() _require_campaign_profile_use_if_needed(session, principal, campaign_id, payload.version_id) try: result = queue_failed_jobs_for_retry( session, tenant_id=principal.tenant_id, campaign_id=campaign_id, version_id=payload.version_id, job_ids=payload.job_ids or None, include_permanent=payload.include_permanent, force_max_attempts=payload.force_max_attempts, enqueue_celery=payload.enqueue_celery, dry_run=payload.dry_run, ) audit_from_principal( session, principal, action="campaign.jobs_retry_queued" if not payload.dry_run else "campaign.jobs_retry_dry_run", object_type="campaign", object_id=campaign_id, details=result, commit=True, ) return CampaignActionResponse(result=result) except (QueueingError, ExecutionSnapshotError) as exc: raise HTTPException(status_code=status.HTTP_422_UNPROCESSABLE_CONTENT, detail=str(exc)) from exc @router.post("/{campaign_id}/jobs/send-unattempted", response_model=CampaignActionResponse) def send_unattempted_campaign_jobs( campaign_id: str, payload: CampaignSendUnattemptedRequest | None = None, session: Session = Depends(get_session), principal: ApiPrincipal = Depends(require_scope("campaigns:campaign:queue")), ): _get_campaign_for_principal(session, campaign_id, principal, write=True) _require_permission(principal, "campaigns:recipient:read") payload = payload or CampaignSendUnattemptedRequest() _require_campaign_profile_use_if_needed(session, principal, campaign_id, payload.version_id) try: result = queue_unattempted_jobs( session, tenant_id=principal.tenant_id, campaign_id=campaign_id, version_id=payload.version_id, job_ids=payload.job_ids or None, enqueue_celery=payload.enqueue_celery, dry_run=payload.dry_run, ) audit_from_principal( session, principal, action="campaign.unattempted_jobs_queued" if not payload.dry_run else "campaign.unattempted_jobs_dry_run", object_type="campaign", object_id=campaign_id, details=result, commit=True, ) return CampaignActionResponse(result=result) except (QueueingError, ExecutionSnapshotError) as exc: raise HTTPException(status_code=status.HTTP_422_UNPROCESSABLE_CONTENT, detail=str(exc)) from exc @router.post("/{campaign_id}/jobs/{job_id}/send", response_model=CampaignActionResponse) def send_single_campaign_job_endpoint( campaign_id: str, job_id: str, payload: CampaignSendJobRequest | None = None, session: Session = Depends(get_session), principal: ApiPrincipal = Depends(require_scope("campaigns:campaign:send")), ): _get_campaign_for_principal(session, campaign_id, principal, write=True) _require_permission(principal, "campaigns:recipient:read") payload = payload or CampaignSendJobRequest() _require_campaign_profile_use_if_needed(session, principal, campaign_id, None) try: result = send_single_campaign_job( session, tenant_id=principal.tenant_id, campaign_id=campaign_id, job_id=job_id, include_warnings=payload.include_warnings, dry_run=payload.dry_run, use_rate_limit=payload.use_rate_limit, enqueue_imap_task=payload.enqueue_imap_task, ) audit_from_principal( session, principal, action="campaign.single_message_sent" if not payload.dry_run else "campaign.single_message_send_dry_run", object_type="campaign_job", object_id=job_id, details=result, commit=True, ) return CampaignActionResponse(result=result) except (QueueingError, ExecutionSnapshotError) as exc: raise HTTPException(status_code=status.HTTP_422_UNPROCESSABLE_CONTENT, detail=str(exc)) from exc except Exception as exc: raise HTTPException(status_code=status.HTTP_422_UNPROCESSABLE_CONTENT, detail=str(exc)) from exc @router.post("/{campaign_id}/jobs/{job_id}/resolve-outcome", response_model=CampaignActionResponse) def resolve_campaign_job_outcome( campaign_id: str, job_id: str, payload: CampaignResolveOutcomeRequest, session: Session = Depends(get_session), principal: ApiPrincipal = Depends(require_scope("campaigns:campaign:reconcile")), ): _get_campaign_for_principal(session, campaign_id, principal, write=True) _require_permission(principal, "campaigns:recipient:read") try: result = reconcile_job_outcome( session, tenant_id=principal.tenant_id, campaign_id=campaign_id, job_id=job_id, decision=payload.decision, note=payload.note, attempt_id=payload.attempt_id, commit=False, ) audit_from_principal( session, principal, action="campaign.job_outcome_reconciled", object_type="campaign_job", object_id=job_id, details=result, commit=True, ) return CampaignActionResponse(result=result) except (QueueingError, ExecutionSnapshotError) as exc: session.rollback() raise HTTPException(status_code=status.HTTP_422_UNPROCESSABLE_CONTENT, detail=str(exc)) from exc except Exception: session.rollback() raise @router.post("/{campaign_id}/mock-send", response_model=MockCampaignSendResponse) def mock_send_campaign( campaign_id: str, payload: MockCampaignSendRequest | None = None, session: Session = Depends(get_session), principal: ApiPrincipal = Depends(require_scope("campaigns:campaign:send_test")), ): """Run a fully visible mock delivery flow without mutating campaign state. The route validates and builds the selected version, then optionally records mock SMTP deliveries and mock IMAP appends. It never talks to the configured real SMTP/IMAP servers and it does not mark the version sent/final. """ _get_campaign_for_principal(session, campaign_id, principal, write=True) _require_permission(principal, "campaigns:recipient:read") payload = payload or MockCampaignSendRequest() _require_campaign_profile_use_if_needed(session, principal, campaign_id, payload.version_id) try: result = run_mock_campaign_send( session, tenant_id=principal.tenant_id, campaign_id=campaign_id, version_id=payload.version_id, send=payload.send, include_warnings=payload.include_warnings, include_needs_review=payload.include_needs_review, append_sent=payload.append_sent, clear_mailbox=payload.clear_mailbox, check_files=payload.check_files, ) audit_from_principal( session, principal, action="campaign.mock_send" if payload.send else "campaign.mock_send_review", object_type="campaign", object_id=campaign_id, details={ "version_id": result.get("version_id"), "send_requested": payload.send, "sent_count": result.get("send", {}).get("sent_count"), "failed_count": result.get("send", {}).get("failed_count"), }, commit=True, ) return MockCampaignSendResponse(result=result) except MockCampaignSendError as exc: raise HTTPException(status_code=status.HTTP_422_UNPROCESSABLE_CONTENT, detail=str(exc)) from exc except Exception as exc: raise HTTPException(status_code=status.HTTP_422_UNPROCESSABLE_CONTENT, detail=str(exc)) from exc @router.post("/{campaign_id}/send-now", response_model=SendCampaignNowResponse) def send_campaign_now_endpoint( campaign_id: str, payload: SendCampaignNowRequest | None = None, session: Session = Depends(get_session), principal: ApiPrincipal = Depends(require_scope("campaigns:campaign:send")), ): """Preflight and synchronously send a policy-bounded built execution.""" _get_campaign_for_principal(session, campaign_id, principal, write=True) _require_permission(principal, "campaigns:recipient:read") payload = payload or SendCampaignNowRequest() try: campaign = _get_campaign_for_tenant(session, campaign_id, principal.tenant_id) version_id = payload.version_id or campaign.current_version_id if not version_id: raise HTTPException(status_code=status.HTTP_422_UNPROCESSABLE_CONTENT, detail="Campaign has no current version") version = _get_version_for_tenant(session, version_id, principal.tenant_id) _require_mail_profile_use_if_needed(principal, version.raw_json if isinstance(version.raw_json, dict) else {}) validation_result: dict[str, object] | None = version.validation_summary if isinstance(version.validation_summary, dict) else None build_result: dict[str, object] | None = version.build_summary if isinstance(version.build_summary, dict) else None if is_user_locked_version(version): raise HTTPException( status_code=status.HTTP_409_CONFLICT, detail="User-locked audit-safe versions cannot be dry-run or sent. Create an editable copy and validate it instead.", ) if not version.locked_at or not validation_result or validation_result.get("ok") is not True: raise HTTPException( status_code=status.HTTP_422_UNPROCESSABLE_CONTENT, detail="Campaign version must be validated and locked before dry-run or sending.", ) if not build_result: raise HTTPException( status_code=status.HTTP_422_UNPROCESSABLE_CONTENT, detail="Campaign version must be built before dry-run or sending.", ) delivery_result = send_campaign_now( session, tenant_id=principal.tenant_id, campaign_id=campaign_id, version_id=version_id, include_warnings=payload.include_warnings, dry_run=payload.dry_run, use_rate_limit=payload.use_rate_limit, enqueue_imap_task=payload.enqueue_imap_task, ).as_dict() response_result = public_send_campaign_now_result( delivery_result, validation_summary=validation_result, build_summary=build_result, ) audit_from_principal( session, principal, action="campaign.sent_now" if not payload.dry_run else "campaign.send_now_dry_run", object_type="campaign", object_id=campaign_id, details=send_campaign_now_audit_details(delivery_result), commit=True, ) return SendCampaignNowResponse(result=response_result) except SynchronousSendRejected as exc: # A synchronous request stages queue state before the all-message # preflight can run. Rejecting that preflight must not leave work # eligible for a background worker when no provider effect occurred. session.rollback() audit_from_principal( session, principal, action="campaign.send_now_rejected", object_type="campaign", object_id=campaign_id, details={ **exc.audit_details(), "version_id": payload.version_id, }, commit=True, ) raise HTTPException(status_code=status.HTTP_422_UNPROCESSABLE_CONTENT, detail=str(exc)) from exc except HTTPException: raise except (CampaignPersistenceError, QueueingError) as exc: raise HTTPException(status_code=status.HTTP_422_UNPROCESSABLE_CONTENT, detail=str(exc)) from exc except Exception as exc: raise HTTPException(status_code=status.HTTP_422_UNPROCESSABLE_CONTENT, detail=str(exc)) from exc @router.post("/{campaign_id}/pause", response_model=CampaignActionResponse) def pause_campaign( campaign_id: str, session: Session = Depends(get_session), principal: ApiPrincipal = Depends(require_scope("campaigns:campaign:control")), ): _get_campaign_for_principal(session, campaign_id, principal, write=True) try: result = pause_campaign_jobs(session, tenant_id=principal.tenant_id, campaign_id=campaign_id) audit_from_principal(session, principal, action="campaign.paused", object_type="campaign", object_id=campaign_id, details=result, commit=True) return CampaignActionResponse(result=result) except QueueingError as exc: raise HTTPException(status_code=status.HTTP_422_UNPROCESSABLE_CONTENT, detail=str(exc)) from exc @router.post("/{campaign_id}/resume", response_model=CampaignActionResponse) def resume_campaign( campaign_id: str, session: Session = Depends(get_session), principal: ApiPrincipal = Depends(require_scope("campaigns:campaign:control")), ): _get_campaign_for_principal(session, campaign_id, principal, write=True) version_ids = { row[0] for row in session.query(CampaignJob.campaign_version_id) .filter( CampaignJob.tenant_id == principal.tenant_id, CampaignJob.campaign_id == campaign_id, CampaignJob.queue_status == JobQueueStatus.PAUSED.value, ) .distinct() .all() } _require_campaign_versions_profile_use(session, principal, campaign_id, version_ids) try: result = resume_campaign_jobs(session, tenant_id=principal.tenant_id, campaign_id=campaign_id) audit_from_principal(session, principal, action="campaign.resumed", object_type="campaign", object_id=campaign_id, details=result, commit=True) return CampaignActionResponse(result=result) except QueueingError as exc: raise HTTPException(status_code=status.HTTP_422_UNPROCESSABLE_CONTENT, detail=str(exc)) from exc @router.post("/{campaign_id}/cancel", response_model=CampaignActionResponse) def cancel_campaign( campaign_id: str, session: Session = Depends(get_session), principal: ApiPrincipal = Depends(require_scope("campaigns:campaign:control")), ): _get_campaign_for_principal(session, campaign_id, principal, write=True) try: result = cancel_campaign_jobs(session, tenant_id=principal.tenant_id, campaign_id=campaign_id) audit_from_principal(session, principal, action="campaign.cancelled", object_type="campaign", object_id=campaign_id, details=result, commit=True) return CampaignActionResponse(result=result) except QueueingError as exc: raise HTTPException(status_code=status.HTTP_422_UNPROCESSABLE_CONTENT, detail=str(exc)) from exc @router.post("/{campaign_id}/append-sent", response_model=CampaignActionResponse) def append_sent( campaign_id: str, payload: AppendSentRequest | None = None, session: Session = Depends(get_session), principal: ApiPrincipal = Depends(require_scope("campaigns:campaign:send")), ): _get_campaign_for_principal(session, campaign_id, principal, write=True) payload = payload or AppendSentRequest() version_ids = { row[0] for row in session.query(CampaignJob.campaign_version_id) .filter( CampaignJob.tenant_id == principal.tenant_id, CampaignJob.campaign_id == campaign_id, CampaignJob.send_status.in_( [JobSendStatus.SMTP_ACCEPTED.value, JobSendStatus.SENT.value] ), CampaignJob.imap_status.in_( [JobImapStatus.PENDING.value, JobImapStatus.FAILED.value] ), ) .distinct() .all() } _require_campaign_versions_profile_use(session, principal, campaign_id, version_ids) try: result = enqueue_pending_imap_appends( session, tenant_id=principal.tenant_id, campaign_id=campaign_id, enqueue_celery=payload.enqueue_celery, run_inline=payload.run_inline, dry_run=payload.dry_run, ) audit_from_principal( session, principal, action="campaign.append_sent_enqueued" if not payload.dry_run else "campaign.append_sent_dry_run", object_type="campaign", object_id=campaign_id, details=result, commit=True, ) return CampaignActionResponse(result=result) except QueueingError as exc: raise HTTPException(status_code=status.HTTP_422_UNPROCESSABLE_CONTENT, detail=str(exc)) from exc class CampaignAttachmentPreviewRequest(BaseModel): include_unmatched: bool = True include_unlinked_candidates: bool = False campaign_json: dict[str, object] | None = None class CampaignAttachmentPreviewResponse(BaseModel): campaign_id: str version_id: str shared_file_count: int candidate_file_count: int = 0 matched_file_count: int = 0 linked_file_count: int = 0 unlinked_file_count: int = 0 rules: list[dict[str, object]] = Field(default_factory=list) linkable_files: list[dict[str, object]] = Field(default_factory=list) unused_shared_files: list[dict[str, object]] = Field(default_factory=list) class CampaignAttachmentLinkMatchesRequest(BaseModel): campaign_json: dict[str, object] | None = None dry_run: bool = False class CampaignAttachmentLinkMatchesResponse(BaseModel): campaign_id: str version_id: str matched_file_count: int already_linked_file_count: int linked_file_count: int dry_run: bool = False linked_files: list[dict[str, object]] = Field(default_factory=list) linkable_files: list[dict[str, object]] = Field(default_factory=list) def _file_preview(session: Session, asset) -> dict[str, object]: version, blob = files_integration().current_version_and_blob(session, asset) return { "id": asset.id, "version_id": version.id, "blob_id": blob.id, "display_path": asset.display_path, "filename": asset.filename, "owner_type": asset.owner_type, "owner_id": asset.owner_user_id if asset.owner_type == "user" else asset.owner_group_id, "checksum_sha256": blob.checksum_sha256, "size_bytes": blob.size_bytes, "content_type": blob.content_type, "linked_to_campaign": True, } def _managed_preview_file(item: dict[str, object]) -> dict[str, object]: return { "id": item["asset_id"], "version_id": item["version_id"], "blob_id": item["blob_id"], "display_path": item["display_path"], "filename": item["filename"], "owner_type": item["owner_type"], "owner_id": item["owner_id"], "checksum_sha256": item["checksum_sha256"], "size_bytes": item["size_bytes"], "content_type": item["content_type"], "linked_to_campaign": bool(item.get("linked_to_campaign", True)), } def _attachment_preview_for_version( session: Session, principal: ApiPrincipal, *, campaign: Campaign, version: CampaignVersion, raw: dict[str, object], include_unmatched: bool, include_unlinked_candidates: bool, ) -> CampaignAttachmentPreviewResponse: files = files_integration() assert_server_safe_campaign_paths(raw, managed_files_available=files.available) with files.prepared_campaign_snapshot( session, tenant_id=principal.tenant_id, campaign_id=campaign.id, raw_json=raw, include_bytes=False, prefix="govoplan-managed-preview-", include_unlinked_candidates=include_unlinked_candidates, user_id=principal.user.id, is_admin=has_scope(principal, "files:file:admin"), ) as prepared: prepared_raw = load_campaign_json(prepared.path) config = load_campaign_config_from_json(session, tenant_id=principal.tenant_id, raw_json=prepared_raw, campaign_id=campaign.id) report = resolve_campaign_attachments(config, campaign_file=prepared.path) rules: list[dict[str, object]] = [] matched_asset_ids: set[str] = set() linked_asset_ids: set[str] = set() linkable_by_id: dict[str, dict[str, object]] = {} for entry in report.entries: for attachment in entry.attachments: managed_matches = files.managed_match_payloads(attachment.matches, prepared.managed_files_by_local_path) matches: list[dict[str, object]] = [] for item in managed_matches: asset_id = str(item["asset_id"]) matched_asset_ids.add(asset_id) if bool(item.get("linked_to_campaign", True)): linked_asset_ids.add(asset_id) preview = _managed_preview_file(item) matches.append(preview) if not preview["linked_to_campaign"]: linkable_by_id.setdefault(asset_id, preview) if not matches: matches = [ { "id": "", "display_path": match, "filename": match.rsplit("/", 1)[-1].rsplit("\\", 1)[-1], "owner_type": "legacy", "owner_id": "", "linked_to_campaign": True, } for match in attachment.matches ] rules.append({ "source": attachment.scope.value, "entry_index": entry.entry_index, "entry_id": entry.entry_id, "index": attachment.index, "attachment_id": attachment.attachment_id, "label": attachment.label, "required": attachment.required, "pattern": attachment.file_filter, "base_path_name": attachment.base_path_name, "base_path": attachment.base_path, "status": attachment.status.value, "behavior": attachment.behavior.value if attachment.behavior else None, "zip_included": attachment.zip_enabled, "zip_mode": attachment.zip_mode.value, "zip_archive_id": attachment.zip_archive_id, "zip_filename": attachment.zip_filename, "matches": matches, "match_count": len(matches), "linked_match_count": sum(1 for match in matches if bool(match.get("linked_to_campaign", True))), "unlinked_match_count": sum(1 for match in matches if not bool(match.get("linked_to_campaign", True))), "issues": [issue.model_dump(mode="json") for issue in attachment.issues], }) unused = [asset for asset in prepared.shared_assets if asset.id not in matched_asset_ids] return CampaignAttachmentPreviewResponse( campaign_id=campaign.id, version_id=version.id, shared_file_count=len(prepared.shared_assets), candidate_file_count=len(getattr(prepared, "candidate_assets", prepared.shared_assets)), matched_file_count=len(matched_asset_ids), linked_file_count=len(linked_asset_ids), unlinked_file_count=len(linkable_by_id), rules=rules, linkable_files=list(linkable_by_id.values()), unused_shared_files=[_file_preview(session, asset) for asset in unused] if include_unmatched else [], ) def _link_campaign_attachment_matches( session: Session, principal: ApiPrincipal, *, campaign: Campaign, version: CampaignVersion, raw: dict[str, object], dry_run: bool = False, ) -> CampaignAttachmentLinkMatchesResponse: preview = _attachment_preview_for_version( session, principal, campaign=campaign, version=version, raw=raw, include_unmatched=False, include_unlinked_candidates=True, ) file_ids = [str(item.get("id") or "") for item in preview.linkable_files if item.get("id")] linked_files: list[dict[str, object]] = [] if file_ids and not dry_run: files = files_integration() shares = files.share_assets_with_campaign( session, tenant_id=principal.tenant_id, campaign_id=campaign.id, file_ids=file_ids, user_id=principal.user.id, is_admin=has_scope(principal, "files:file:admin"), ) share_by_asset_id = {str(item.get("file_asset_id") or ""): item for item in shares} linked_files = [ {**item, "share": share_by_asset_id.get(str(item.get("id") or ""))} for item in preview.linkable_files ] return CampaignAttachmentLinkMatchesResponse( campaign_id=campaign.id, version_id=version.id, matched_file_count=preview.matched_file_count, already_linked_file_count=preview.linked_file_count, linked_file_count=0 if dry_run else len(file_ids), dry_run=dry_run, linked_files=linked_files, linkable_files=preview.linkable_files, ) @router.post("/{campaign_id}/versions/{version_id}/attachments/preview", response_model=CampaignAttachmentPreviewResponse) def preview_campaign_attachments( campaign_id: str, version_id: str, payload: CampaignAttachmentPreviewRequest | None = None, session: Session = Depends(get_session), principal: ApiPrincipal = Depends(require_scope("files:file:read")), ): _get_campaign_for_principal(session, campaign_id, principal) _require_permission(principal, "campaigns:recipient:read") campaign = _get_campaign_for_tenant(session, campaign_id, principal.tenant_id) version = _get_version_for_tenant(session, version_id, principal.tenant_id) if version.campaign_id != campaign.id: raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Campaign version not found") payload = payload or CampaignAttachmentPreviewRequest() raw = payload.campaign_json if isinstance(payload.campaign_json, dict) else version.raw_json raw = raw if isinstance(raw, dict) else {} _require_mail_profile_use_if_needed(principal, raw) try: return _attachment_preview_for_version( session, principal, campaign=campaign, version=version, raw=raw, include_unmatched=payload.include_unmatched, include_unlinked_candidates=payload.include_unlinked_candidates, ) except CampaignPathSecurityError as exc: raise HTTPException(status_code=status.HTTP_422_UNPROCESSABLE_CONTENT, detail=str(exc)) from exc @router.post("/{campaign_id}/versions/{version_id}/attachments/link-matches", response_model=CampaignAttachmentLinkMatchesResponse) def link_campaign_attachment_matches( campaign_id: str, version_id: str, payload: CampaignAttachmentLinkMatchesRequest | None = None, session: Session = Depends(get_session), principal: ApiPrincipal = Depends(require_scope("campaigns:campaign:validate")), ): _require_permission(principal, "files:file:share") _get_campaign_for_principal(session, campaign_id, principal, write=True) _require_permission(principal, "campaigns:recipient:read") campaign = _get_campaign_for_tenant(session, campaign_id, principal.tenant_id) version = _get_version_for_tenant(session, version_id, principal.tenant_id) if version.campaign_id != campaign.id: raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Campaign version not found") if is_user_locked_version(version) or is_version_final_locked(version): raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail="Locked campaign versions cannot link new attachment files") payload = payload or CampaignAttachmentLinkMatchesRequest() raw = payload.campaign_json if isinstance(payload.campaign_json, dict) else version.raw_json raw = raw if isinstance(raw, dict) else {} _require_mail_profile_use_if_needed(principal, raw) try: result = _link_campaign_attachment_matches( session, principal, campaign=campaign, version=version, raw=raw, dry_run=payload.dry_run, ) audit_from_principal( session, principal, action="campaign.attachment_matches_linked" if not payload.dry_run else "campaign.attachment_matches_link_previewed", object_type="campaign_version", object_id=version_id, details={ "matched_file_count": result.matched_file_count, "already_linked_file_count": result.already_linked_file_count, "linked_file_count": result.linked_file_count, "dry_run": result.dry_run, }, commit=True, ) return result except HTTPException: raise except Exception as exc: session.rollback() raise HTTPException(status_code=status.HTTP_422_UNPROCESSABLE_CONTENT, detail=str(exc)) from exc