"""Workspace Human Input v2 Contact management and editor APIs.""" from __future__ import annotations from http import HTTPStatus from typing import Never from uuid import UUID from flask import abort, request from flask_restx import Resource from sqlalchemy.orm import Session from controllers.common.human_input_v2_contracts import ( AddPlatformContactsRequest, AddPlatformContactsResponse, BatchGetContactOptionsQuery, BatchGetContactOptionsResponse, BatchGetContactsQuery, BatchGetContactsResponse, ContactListQuery, ContactOption, ContactOptionsQuery, CreateIMBindingRequest, CreateIMBindingResponse, CreateIMSyncRunResponse, DeleteIMBindingResponse, ExternalContactCreateRequest, ExternalContactCreateResponse, ExternalContactUpdateRequest, ExternalContactUpdateResponse, GetContactResponse, GetLatestIMSyncRunResponse, HumanInputContact, HumanInputContactType, IMContactSyncErrorResponse, IMProvider, IMSyncResultType, IMSyncRunStatus, ListContactOptionsResponse, ListContactsResponse, ListIMIdentitiesQuery, ListIMIdentitiesResponse, ListLatestIMSyncRunResultsQuery, ListLatestIMSyncRunResultsResponse, ListOrganizationCandidatesResponse, NodeDataMigrationFailureResponse, NodeDataMigrationPayload, NodeDataMigrationResponse, OrganizationCandidatesQuery, RemoveContactsRequest, RemoveContactsResponse, ResetContactIMOverrideResponse, SetContactIMOverrideRequest, SetContactIMOverrideResponse, ) from controllers.common.human_input_v2_migration import preflight_legacy_human_input_node_data from controllers.common.schema import ( query_params_from_model, query_params_from_request, register_enum_models, register_response_schema_models, register_schema_models, ) from controllers.common.session import with_session from controllers.console import console_ns from controllers.console.workspace.error import IMBindingReadOnlyError, WorkspaceIMOverrideNotAllowedError from controllers.console.wraps import ( account_initialization_required, edit_permission_required, only_edition_enterprise, setup_required, with_current_tenant_id, with_current_user, ) from core.human_input_v2.im_integration import ( ContactIMBindingView, IMBindingCommandError, IMBindingCommandErrorCode, IMSyncRun, SyncContactSnapshot, SyncResultFact, ) from core.human_input_v2.shared import ( AccountId, ContactId, DeploymentScope, DirectoryScope, IMIdentityId, TenantId, WorkspaceScope, ) from libs.datetime_utils import naive_utc_now from libs.helper import build_avatar_url, dump_response from libs.login import login_required from libs.uuid_utils import uuidv7 from models.account import Account from repositories.human_input_v2.contact import ( CandidateId, Contact, ContactError, ContactErrorCode, ContactQuery, ContactType, ExternalContact, ) from repositories.human_input_v2.sqlalchemy_contact_repository import ( SQLAlchemyContactIMBindingRepository, SQLAlchemyContactRepository, ) from repositories.human_input_v2.sqlalchemy_im_channel_repository import ( DeploymentIMChannelReader, WorkspaceIMChannelReader, ) from repositories.human_input_v2.sqlalchemy_im_identity_repository import SQLAlchemyIMIdentityRepository from services.enterprise.human_input_contact_composition import build_enterprise_contact_management_service from services.feature_service import FeatureService from services.human_input_v2.composition import build_human_input_node_data_migration_service from services.human_input_v2.contact_service import ContactManagementService, ContactWithIMBindings from services.human_input_v2.im_contact_sync.composition import build_im_contact_sync_application from services.human_input_v2.im_contact_sync.errors import IMWriteUnavailableError from services.human_input_v2.im_contact_sync.service import ( IMChannelNotConfiguredError, IMSyncDispatchUnavailableError, IMSyncRevisionChangedError, IMSyncRunNotFoundError, ) from services.human_input_v2.node_data_migration import MigrationNode, NodeDataMigrationFailure from ._decorators import require_admin_or_owner, require_editor register_enum_models( console_ns, HumanInputContactType, IMSyncRunStatus, IMSyncResultType, IMProvider, ) register_schema_models( console_ns, ContactListQuery, ContactOptionsQuery, BatchGetContactOptionsQuery, OrganizationCandidatesQuery, AddPlatformContactsRequest, ExternalContactCreateRequest, ExternalContactUpdateRequest, RemoveContactsRequest, ListIMIdentitiesQuery, ListLatestIMSyncRunResultsQuery, SetContactIMOverrideRequest, CreateIMBindingRequest, NodeDataMigrationPayload, ) register_response_schema_models( console_ns, HumanInputContact, ContactOption, GetContactResponse, ExternalContactCreateResponse, ExternalContactUpdateResponse, AddPlatformContactsResponse, ListContactsResponse, ListContactOptionsResponse, BatchGetContactOptionsResponse, RemoveContactsResponse, ListIMIdentitiesResponse, CreateIMSyncRunResponse, IMContactSyncErrorResponse, GetLatestIMSyncRunResponse, ListLatestIMSyncRunResultsResponse, ListOrganizationCandidatesResponse, ResetContactIMOverrideResponse, SetContactIMOverrideResponse, CreateIMBindingResponse, DeleteIMBindingResponse, BatchGetContactsResponse, NodeDataMigrationResponse, NodeDataMigrationFailureResponse, ) _IM_BINDING_ERROR_STATUS = { IMBindingCommandErrorCode.INTEGRATION_NOT_CONFIGURED: HTTPStatus.NOT_FOUND, IMBindingCommandErrorCode.CONTACT_NOT_FOUND: HTTPStatus.NOT_FOUND, IMBindingCommandErrorCode.IDENTITY_NOT_FOUND: HTTPStatus.NOT_FOUND, IMBindingCommandErrorCode.BINDING_NOT_FOUND: HTTPStatus.NOT_FOUND, IMBindingCommandErrorCode.BINDING_CONFLICT: HTTPStatus.CONFLICT, IMBindingCommandErrorCode.INVALID_SCOPE: HTTPStatus.UNPROCESSABLE_ENTITY, } def _workspace_scope(tenant_id: str) -> WorkspaceScope: return WorkspaceScope(id=TenantId(tenant_id)) def _im_binding_scope(tenant_id: str) -> DirectoryScope: if FeatureService.is_im_centrally_managed(): return DeploymentScope() return _workspace_scope(tenant_id) type _IMApplicationError = ( IMBindingCommandError | IMChannelNotConfiguredError | IMSyncDispatchUnavailableError | IMSyncRevisionChangedError | IMSyncRunNotFoundError | IMWriteUnavailableError ) def _im_application_error_response(error: _IMApplicationError) -> tuple[dict[str, object], HTTPStatus]: if isinstance(error, IMBindingCommandError): status = _IM_BINDING_ERROR_STATUS[error.code] code = error.code.value elif isinstance(error, IMChannelNotConfiguredError): status = HTTPStatus.NOT_FOUND code = "im_integration_not_configured" elif isinstance(error, IMSyncRunNotFoundError): status = HTTPStatus.NOT_FOUND code = "im_sync_run_not_found" elif isinstance(error, IMSyncDispatchUnavailableError): status = HTTPStatus.SERVICE_UNAVAILABLE code = "im_sync_dispatch_unavailable" elif isinstance(error, IMWriteUnavailableError): status = HTTPStatus.SERVICE_UNAVAILABLE code = "im_write_unavailable" else: status = HTTPStatus.CONFLICT code = "im_sync_revision_changed" return ( dump_response( IMContactSyncErrorResponse, {"code": code, "message": str(error), "status": status}, ), status, ) def _sync_run_payload(run: IMSyncRun) -> dict[str, object]: return { "id": run.id, "status": run.status, "started_at": run.started_at, "finished_at": run.finished_at, "error_message": run.error_message, "result_counts": { "added": run.added_count, "not_matched": run.not_matched_count, "failed": run.failed_count, "removed": run.removed_count, "skipped": run.skipped_count, }, "provider": run.provider, "channel_id": run.channel_revision.channel_id, "channel_config_version": run.channel_revision.config_version, } def _directory_entry_payload(result: SyncResultFact) -> dict[str, object] | None: if result.provider_user_id is None: return None return { "provider_user_id": result.provider_user_id, "display_name": result.display_name, "email": result.email, } def _avatar_url(avatar_file_id: str | None) -> str: return build_avatar_url(avatar_file_id) or "" def _sync_contact_payload(contact: SyncContactSnapshot, fallback_created_at) -> dict[str, object]: # Historical result snapshots predate the Contact creation-time field. created_at = contact.created_at if contact.created_at is not None else fallback_created_at return { "id": contact.contact_id, "name": contact.name, "avatar_url": _avatar_url(contact.avatar_file_id), "created_at": created_at, } def _sync_result_payload(result: SyncResultFact) -> dict[str, object]: entry = _directory_entry_payload(result) if result.result_type is IMSyncResultType.NOT_MATCHED: return {"type": result.result_type, "entry": entry} if result.result_type is IMSyncResultType.FAILED: return { "type": result.result_type, "entry": entry, "reason": result.reason_message or result.reason_code or "sync_failed", } if result.result_type is IMSyncResultType.ADDED: if result.contact_snapshot is None or entry is None: raise RuntimeError("added sync result is missing its persisted display snapshot") return { "type": result.result_type, "contact": _sync_contact_payload(result.contact_snapshot, result.created_at), "entry": entry, } if result.result_type is IMSyncResultType.SKIPPED: if result.contact_snapshot is None: raise RuntimeError("skipped sync result is missing its persisted Contact snapshot") return { "type": result.result_type, "entry": entry, "contact": _sync_contact_payload(result.contact_snapshot, result.created_at), } if result.contact_snapshot is None or result.identity_snapshot is None or result.removal_reason is None: raise RuntimeError("removed sync result is missing its persisted display snapshot") return { "type": result.result_type, "contact": _sync_contact_payload(result.contact_snapshot, result.created_at), "last_known_identity": { "identity_id": result.identity_snapshot.identity_id, "provider_user_id": result.identity_snapshot.provider_user_id, "display_name": result.identity_snapshot.display_name, "email": result.identity_snapshot.email, }, "reason": result.removal_reason, } def _contact_binding_payload(contact: ContactIMBindingView) -> dict[str, object]: return { "id": contact.id, "type": contact.type, "name": contact.name, "email": contact.email, "avatar_url": _avatar_url(contact.avatar_file_id), "im_bindings": [ {"id": binding.id, "provider": binding.provider, "scope": binding.scope} for binding in contact.im_bindings ], "created_at": contact.created_at, } def _contact_avatar_url(contact: Contact) -> str: return _avatar_url(contact.avatar_file_id) def _contact_payload(view: ContactWithIMBindings) -> dict[str, object]: contact = view.contact return { "id": contact.id, "type": contact.type, "name": contact.name, "email": contact.email, "avatar_url": _contact_avatar_url(contact), "im_bindings": [ {"id": binding.id, "provider": binding.provider, "scope": binding.scope} for binding in view.im_bindings ], "created_at": contact.created_at, } def _contact_option_payload(view: ContactWithIMBindings) -> dict[str, object]: contact = view.contact return { "id": contact.id, "type": contact.type, "name": contact.name, "avatar_url": _contact_avatar_url(contact) or None, "email": contact.email, "im_providers": list(dict.fromkeys(binding.provider for binding in view.im_bindings)), } def _contact_summary_payload(view: ContactWithIMBindings) -> dict[str, object]: contact = view.contact return { "id": contact.id, "name": contact.name, "avatar_url": _contact_avatar_url(contact), "created_at": contact.created_at, } def _contact_service(session: Session, tenant_id: TenantId) -> ContactManagementService: repository = SQLAlchemyContactRepository(session) if FeatureService.is_im_centrally_managed(): channel = DeploymentIMChannelReader(session).get() else: channel = WorkspaceIMChannelReader(session, tenant_id).get() return ContactManagementService( repository, SQLAlchemyContactIMBindingRepository(session, channel), SQLAlchemyIMIdentityRepository(session, channel.id) if channel is not None else None, ) def _raise_contact_error(error: ContactError) -> Never: if error.code in {ContactErrorCode.NOT_FOUND, ContactErrorCode.ACCOUNT_NOT_FOUND}: abort(HTTPStatus.NOT_FOUND, str(error)) if error.code is ContactErrorCode.CONFLICT: abort(HTTPStatus.CONFLICT, str(error)) abort(HTTPStatus.UNPROCESSABLE_ENTITY, str(error)) @console_ns.route("/workspaces/current/human-input/v2/contacts") class WorkspaceContactsApi(Resource): @console_ns.doc(params=query_params_from_model(ContactListQuery)) @console_ns.response(200, "Success", console_ns.models[ListContactsResponse.__name__]) @require_admin_or_owner @with_current_tenant_id @with_session(write=False) def get(self, session: Session, tenant_id: str): query = ContactListQuery.model_validate(request.args.to_dict(flat=True)) contact_query = ContactQuery( keyword=query.keyword or "", contact_type=ContactType(query.group.value) if query.group is not None else None, ) service = _contact_service(session, TenantId(tenant_id)) page, views = service.list_contacts( TenantId(tenant_id), page=query.page, limit=query.limit, query=contact_query, ) return dump_response( ListContactsResponse, { "data": [_contact_payload(view) for view in views], "page": page.page, "limit": page.limit, "total": service.count_contacts(TenantId(tenant_id), contact_query), }, ) @console_ns.route("/workspaces/current/human-input/v2/contacts/") class WorkspaceContactApi(Resource): """Read one contact only when it resolves in the current workspace scope.""" @console_ns.response(200, "Success", console_ns.models[GetContactResponse.__name__]) @console_ns.response(404, "Contact not found or absent in the current workspace") @require_admin_or_owner @with_current_tenant_id @with_session(write=False) def get(self, session: Session, tenant_id: str, contact_id: str): details = _contact_service(session, TenantId(tenant_id)).get_contact_details( TenantId(tenant_id), ContactId(contact_id) ) if details is None: abort(HTTPStatus.NOT_FOUND, "Contact not found") return dump_response( GetContactResponse, { "contact": _contact_payload(details.contact), "im_binding_details": [ { "id": detail.binding.id, "provider": detail.binding.provider, "scope": detail.binding.scope, "identity": detail.identity, } for detail in details.im_binding_details ], }, ) @console_ns.route("/workspaces/current/human-input/v2/contact-options") class WorkspaceContactOptionsApi(Resource): """Search the current workspace's selectable Contact projection for workflow editors.""" @console_ns.doc( params=query_params_from_model(ContactOptionsQuery), description=( "List editor-safe Contact options for static recipient selection. " "The projection includes effective IM providers and omits binding details and management metadata; " "unavailable Contacts are omitted." ), ) @console_ns.response(200, "Success", console_ns.models[ListContactOptionsResponse.__name__]) @require_editor @with_current_tenant_id @with_session(write=False) def get(self, session: Session, tenant_id: str): query = ContactOptionsQuery.model_validate(request.args.to_dict(flat=True)) service = _contact_service(session, TenantId(tenant_id)) page = service.list_contact_options( TenantId(tenant_id), page=query.page, limit=query.limit, keyword=query.keyword or "", ) return dump_response( ListContactOptionsResponse, { "data": [_contact_option_payload(contact) for contact in page.items], "page": page.page, "limit": page.limit, "total": service.count_contacts(TenantId(tenant_id), ContactQuery(keyword=query.keyword or "")), }, ) @console_ns.route("/workspaces/current/human-input/v2/organization-candidates") class WorkspaceOrganizationCandidatesApi(Resource): @console_ns.doc(params=query_params_from_model(OrganizationCandidatesQuery)) @console_ns.response(200, "Success", console_ns.models[ListOrganizationCandidatesResponse.__name__]) @require_admin_or_owner @only_edition_enterprise @with_current_tenant_id @with_session(write=False) def get(self, session: Session, tenant_id: str): query = OrganizationCandidatesQuery.model_validate(request.args.to_dict(flat=True)) service = build_enterprise_contact_management_service(session) candidates = service.list_organization_candidates( page=query.page, limit=query.limit, keyword=query.keyword or "", ) return dump_response( ListOrganizationCandidatesResponse, { "data": [ { "id": candidate.id, "name": candidate.name, "email": candidate.email, "avatar_url": _avatar_url(candidate.avatar_file_id) or None, } for candidate in candidates ], "page": query.page, "limit": query.limit, "total": service.count_organization_candidates(query.keyword or ""), }, ) @console_ns.route("/workspaces/current/human-input/v2/contacts/platform") class WorkspacePlatformContactsApi(Resource): @console_ns.expect(console_ns.models[AddPlatformContactsRequest.__name__]) @console_ns.response(200, "Success", console_ns.models[AddPlatformContactsResponse.__name__]) @require_admin_or_owner @only_edition_enterprise @with_current_user @with_current_tenant_id @with_session def post(self, session: Session, tenant_id: str, current_user: Account): request_body = AddPlatformContactsRequest.model_validate(console_ns.payload or {}) try: contacts = build_enterprise_contact_management_service(session).add_platform_contacts( TenantId(tenant_id), [CandidateId(candidate_id) for candidate_id in request_body.candidate_ids], AccountId(current_user.id), ) except ContactError as error: _raise_contact_error(error) return dump_response(AddPlatformContactsResponse, {"data": [_contact_payload(contact) for contact in contacts]}) @console_ns.route("/workspaces/current/human-input/v2/contacts/external") class WorkspaceExternalContactsApi(Resource): @console_ns.expect(console_ns.models[ExternalContactCreateRequest.__name__]) @console_ns.response(200, "Success", console_ns.models[ExternalContactCreateResponse.__name__]) @require_admin_or_owner @with_current_tenant_id @with_session def post(self, session: Session, tenant_id: str): request_body = ExternalContactCreateRequest.model_validate(console_ns.payload or {}) try: contact = _contact_service(session, TenantId(tenant_id)).create_external_contact( TenantId(tenant_id), contact_id=ContactId(str(uuidv7())), name=request_body.name, email=str(request_body.email), avatar_file_id=request_body.avatar or None, now=naive_utc_now(), ) except ContactError as error: _raise_contact_error(error) return dump_response(ExternalContactCreateResponse, {"contact": _contact_payload(contact)}) @console_ns.route("/workspaces/current/human-input/v2/contacts/external/") class WorkspaceExternalContactApi(Resource): @console_ns.expect(console_ns.models[ExternalContactUpdateRequest.__name__]) @console_ns.response(200, "Success", console_ns.models[ExternalContactUpdateResponse.__name__]) @require_admin_or_owner @with_current_tenant_id @with_session def patch(self, session: Session, tenant_id: str, contact_id: str): request_body = ExternalContactUpdateRequest.model_validate(console_ns.payload or {}) service = _contact_service(session, TenantId(tenant_id)) try: current = service.get_contact(TenantId(tenant_id), ContactId(contact_id)) if current is None or current.contact.type is not ContactType.EXTERNAL: abort(HTTPStatus.NOT_FOUND, "External Contact not found") assert current is not None current_contact = current.contact if current_contact.email is None: raise RuntimeError("External Contact is missing its required Email") avatar_file_id = current_contact.avatar_file_id if "avatar" in request_body.model_fields_set: avatar_file_id = request_body.avatar or None contact = service.update_external_contact( TenantId(tenant_id), external_contact=ExternalContact( id=current_contact.id, name=request_body.name or current_contact.name, email=str(request_body.email) if request_body.email is not None else current_contact.email, avatar_file_id=avatar_file_id, created_at=current_contact.created_at, ), ) except ContactError as error: _raise_contact_error(error) return dump_response(ExternalContactUpdateResponse, {"contact": _contact_payload(contact)}) @console_ns.route("/workspaces/current/human-input/v2/contacts/remove") class WorkspaceContactsRemoveApi(Resource): @console_ns.expect(console_ns.models[RemoveContactsRequest.__name__]) @console_ns.response(200, "Success", console_ns.models[RemoveContactsResponse.__name__]) @require_admin_or_owner @with_current_tenant_id @with_session def post(self, session: Session, tenant_id: str): request_body = RemoveContactsRequest.model_validate(console_ns.payload or {}) try: contact_ids = [ContactId(contact_id) for contact_id in request_body.contact_ids] if FeatureService.is_im_centrally_managed(): removed_ids = build_enterprise_contact_management_service(session).remove_contacts( TenantId(tenant_id), contact_ids, ) else: removed_ids = _contact_service(session, TenantId(tenant_id)).remove_contacts( TenantId(tenant_id), contact_ids ) except ContactError as error: _raise_contact_error(error) except ValueError as error: abort(HTTPStatus.UNPROCESSABLE_ENTITY, str(error)) return dump_response(RemoveContactsResponse, {"removed_contact_ids": removed_ids}) @console_ns.route("/workspaces/current/human-input/v2/im-sync-runs") class WorkspaceIMSyncRunsApi(Resource): @console_ns.response(200, "Success", console_ns.models[CreateIMSyncRunResponse.__name__]) @console_ns.response(404, "IM Integration not configured", console_ns.models[IMContactSyncErrorResponse.__name__]) @console_ns.response(409, "IM Integration revision changed", console_ns.models[IMContactSyncErrorResponse.__name__]) @console_ns.response( 503, "IM synchronization temporarily unavailable", console_ns.models[IMContactSyncErrorResponse.__name__], ) @require_admin_or_owner @with_current_user @with_current_tenant_id def post(self, tenant_id: str, current_user: Account): try: run = build_im_contact_sync_application().sync_service.create_or_get_active_run( _workspace_scope(tenant_id), AccountId(current_user.id), ) except ( IMChannelNotConfiguredError, IMSyncDispatchUnavailableError, IMSyncRevisionChangedError, IMWriteUnavailableError, ) as error: return _im_application_error_response(error) return dump_response(CreateIMSyncRunResponse, {"run": _sync_run_payload(run)}) @console_ns.route("/workspaces/current/human-input/v2/im-sync-runs/latest") class WorkspaceLatestIMSyncRunApi(Resource): @console_ns.doc( description=( "Return the latest IM sync run summary. The UI uses finished_at as the explicit sync time; " "the response does not include started_by." ) ) @console_ns.response(200, "Success", console_ns.models[GetLatestIMSyncRunResponse.__name__]) @console_ns.response(404, "Latest IM sync run not found", console_ns.models[IMContactSyncErrorResponse.__name__]) @require_admin_or_owner @with_current_tenant_id def get(self, tenant_id: str): try: run = build_im_contact_sync_application().sync_service.get_latest_run(_workspace_scope(tenant_id)) except (IMChannelNotConfiguredError, IMSyncRunNotFoundError) as error: return _im_application_error_response(error) return dump_response(GetLatestIMSyncRunResponse, {"run": _sync_run_payload(run)}) @console_ns.route("/workspaces/current/human-input/v2/im-sync-runs/latest/results") class WorkspaceLatestIMSyncRunResultsApi(Resource): @console_ns.doc( params=query_params_from_model(ListLatestIMSyncRunResultsQuery), description=( "Return one required result bucket from the latest IM sync run using page and limit pagination. " "There is no all filter; the response contains page, limit, and total metadata without a run summary." ), ) @console_ns.response(200, "Success", console_ns.models[ListLatestIMSyncRunResultsResponse.__name__]) @console_ns.response(404, "Latest IM sync run not found", console_ns.models[IMContactSyncErrorResponse.__name__]) @require_admin_or_owner @with_current_tenant_id def get(self, tenant_id: str): query = ListLatestIMSyncRunResultsQuery.model_validate(request.args.to_dict(flat=True)) try: result_page = build_im_contact_sync_application().sync_service.list_latest_results( _workspace_scope(tenant_id), query.result, page=query.page, limit=query.limit, ) except (IMChannelNotConfiguredError, IMSyncRunNotFoundError) as error: return _im_application_error_response(error) return dump_response( ListLatestIMSyncRunResultsResponse, { "data": [{"id": result.id, "result": _sync_result_payload(result)} for result in result_page.items], "page": result_page.page, "limit": result_page.limit, "total": result_page.total, }, ) @console_ns.route("/workspaces/current/human-input/v2/im-identities") class WorkspaceIMIdentitiesApi(Resource): @console_ns.doc(params=query_params_from_model(ListIMIdentitiesQuery)) @console_ns.response(200, "Success", console_ns.models[ListIMIdentitiesResponse.__name__]) @console_ns.response(404, "IM Integration not configured", console_ns.models[IMContactSyncErrorResponse.__name__]) @require_admin_or_owner @with_current_tenant_id def get(self, tenant_id: str): query = ListIMIdentitiesQuery.model_validate(request.args.to_dict(flat=True)) try: identity_page = build_im_contact_sync_application().sync_service.search_identities( _im_binding_scope(tenant_id), keyword=query.keyword, page=query.page, limit=query.limit, ) except IMChannelNotConfiguredError as error: return _im_application_error_response(error) return dump_response( ListIMIdentitiesResponse, { "data": identity_page.items, "page": identity_page.page, "limit": identity_page.limit, "total": identity_page.total, }, ) @console_ns.route("/workspaces/current/human-input/v2/contacts//im-override") class WorkspaceContactIMOverrideApi(Resource): @console_ns.doc( description=( "Set or reset the IM override for a contact. " "This endpoint is used to override the IM identity for a contact in the workspace." ), ) @console_ns.expect(console_ns.models[SetContactIMOverrideRequest.__name__]) @console_ns.response(200, "Success", console_ns.models[SetContactIMOverrideResponse.__name__]) @console_ns.response(403, "Workspace overrides require centrally managed IM bindings") @console_ns.response( 404, "Contact or IM identity not found", console_ns.models[IMContactSyncErrorResponse.__name__], ) @console_ns.response(409, "IM binding conflict", console_ns.models[IMContactSyncErrorResponse.__name__]) @console_ns.response(422, "Invalid binding scope", console_ns.models[IMContactSyncErrorResponse.__name__]) @console_ns.response(503, "IM write unavailable", console_ns.models[IMContactSyncErrorResponse.__name__]) @require_admin_or_owner @with_current_user @with_current_tenant_id def put(self, tenant_id: str, current_user: Account, contact_id: str): if not FeatureService.is_im_centrally_managed(): raise WorkspaceIMOverrideNotAllowedError() request_body = SetContactIMOverrideRequest.model_validate(console_ns.payload or {}) tenant_id = TenantId(tenant_id) try: contact = build_im_contact_sync_application().binding_service.set_workspace_override( organization_scope=_im_binding_scope(tenant_id), tenant_id=tenant_id, contact_id=ContactId(contact_id), identity_id=IMIdentityId(request_body.identity_id), bound_by_account_id=AccountId(current_user.id), ) except (IMBindingCommandError, IMWriteUnavailableError) as error: return _im_application_error_response(error) return dump_response(SetContactIMOverrideResponse, {"contact": _contact_binding_payload(contact)}) @console_ns.doc( description=( "Reset the IM override for a contact. " "This endpoint is used to clear the IM identity override for a contact in the workspace." ), ) @console_ns.response(200, "Success", console_ns.models[ResetContactIMOverrideResponse.__name__]) @console_ns.response(403, "Workspace overrides require centrally managed IM bindings") @console_ns.response(404, "Contact not found", console_ns.models[IMContactSyncErrorResponse.__name__]) @console_ns.response(422, "Invalid binding scope", console_ns.models[IMContactSyncErrorResponse.__name__]) @console_ns.response(503, "IM write unavailable", console_ns.models[IMContactSyncErrorResponse.__name__]) @require_admin_or_owner @with_current_tenant_id def delete(self, tenant_id: str, contact_id: str): if not FeatureService.is_im_centrally_managed(): raise WorkspaceIMOverrideNotAllowedError() tenant_id = TenantId(tenant_id) try: contact = build_im_contact_sync_application().binding_service.reset_workspace_override( organization_scope=_im_binding_scope(tenant_id), tenant_id=tenant_id, contact_id=ContactId(contact_id), ) except (IMBindingCommandError, IMWriteUnavailableError) as error: return _im_application_error_response(error) return dump_response(ResetContactIMOverrideResponse, {"contact": _contact_binding_payload(contact)}) @console_ns.route("/workspaces/current/human-input/v2/contacts//im-bindings") class WorkspaceContactIMBindingsApi(Resource): @console_ns.doc( description=( "Set a default IM binding for a contact, atomically replacing any default binding for either " "the contact or the selected identity. Identical assignments preserve their binding ID; " "changed assignments receive a new binding ID. " "This endpoint is not used for creating workspace IM override. " "For that purpose, use WorkspaceContactIMOverrideApi.put instead." ), ) @console_ns.expect(console_ns.models[CreateIMBindingRequest.__name__]) @console_ns.response(200, "Success", console_ns.models[CreateIMBindingResponse.__name__]) @console_ns.response(403, "Centrally managed IM bindings cannot be edited from a workspace") @console_ns.response( 404, "Contact or IM identity not found", console_ns.models[IMContactSyncErrorResponse.__name__], ) @console_ns.response(409, "IM binding conflict", console_ns.models[IMContactSyncErrorResponse.__name__]) @console_ns.response(503, "IM write unavailable", console_ns.models[IMContactSyncErrorResponse.__name__]) @require_admin_or_owner @with_current_user @with_current_tenant_id def put(self, tenant_id: str, current_user: Account, contact_id: str): if FeatureService.is_im_centrally_managed(): raise IMBindingReadOnlyError() request_body = CreateIMBindingRequest.model_validate(console_ns.payload or {}) tenant_id = TenantId(tenant_id) try: contact = build_im_contact_sync_application().binding_service.set_organization_binding( organization_scope=WorkspaceScope(id=tenant_id), tenant_id=tenant_id, contact_id=ContactId(contact_id), identity_id=IMIdentityId(request_body.identity_id), bound_by_account_id=AccountId(current_user.id), ) except (IMBindingCommandError, IMWriteUnavailableError) as error: return _im_application_error_response(error) return dump_response(CreateIMBindingResponse, {"contact": _contact_binding_payload(contact)}) @console_ns.response(200, "Success", console_ns.models[DeleteIMBindingResponse.__name__]) @console_ns.response(403, "Centrally managed IM bindings cannot be edited from a workspace") @console_ns.response(404, "IM binding not found", console_ns.models[IMContactSyncErrorResponse.__name__]) @console_ns.response(503, "IM write unavailable", console_ns.models[IMContactSyncErrorResponse.__name__]) @console_ns.doc( description=( "Delete the current default IM binding for the contact identified by the path. " "Workspace IM overrides are not modified. " "This endpoint is not used for resetting workspace IM override. For that purpose, use " "WorkspaceContactIMOverrideApi.delete instead." ), ) @require_admin_or_owner @with_current_tenant_id def delete(self, tenant_id: str, contact_id: UUID): if FeatureService.is_im_centrally_managed(): raise IMBindingReadOnlyError() try: build_im_contact_sync_application().binding_service.delete_organization_binding( organization_scope=_workspace_scope(tenant_id), contact_id=ContactId(str(contact_id)), ) except (IMBindingCommandError, IMWriteUnavailableError) as error: return _im_application_error_response(error) return dump_response(DeleteIMBindingResponse, {}) @console_ns.route("/workspaces/current/human-input/v2/contacts/batch") class BatchGetContactsAPI(Resource): @console_ns.doc( params=query_params_from_model(BatchGetContactsQuery), description=( "Admin-only batch lookup for Contact management clients. " "Workflow editors must use the editor-safe contact-options/batch projection." ), ) @console_ns.response(200, "Success", console_ns.models[BatchGetContactsResponse.__name__]) @require_admin_or_owner @with_current_tenant_id @with_session(write=False) def get(self, session: Session, tenant_id: str): query = query_params_from_request(BatchGetContactsQuery, list_fields=("contact_ids",)) contacts = _contact_service(session, TenantId(tenant_id)).get_contacts( TenantId(tenant_id), [ContactId(contact_id) for contact_id in query.contact_ids], ) return dump_response( BatchGetContactsResponse, {"data": [_contact_summary_payload(contact) for contact in contacts]}, ) @console_ns.route("/workspaces/current/human-input/v2/contact-options/batch") class BatchGetContactOptionsAPI(Resource): """Resolve persisted Contact IDs through the same editor-safe selection projection.""" @console_ns.doc( params=query_params_from_model(BatchGetContactOptionsQuery), description=( "Resolve Contact IDs persisted in workflow recipient configuration. " "Include effective IM providers for each Contact. " "Contacts unavailable in the current workspace are omitted." ), ) @console_ns.response(200, "Success", console_ns.models[BatchGetContactOptionsResponse.__name__]) @require_editor @with_current_tenant_id @with_session(write=False) def get(self, session: Session, tenant_id: str): query = query_params_from_request(BatchGetContactOptionsQuery, list_fields=("contact_ids",)) contacts = _contact_service(session, TenantId(tenant_id)).get_contact_options( TenantId(tenant_id), [ContactId(contact_id) for contact_id in query.contact_ids], ) return dump_response( BatchGetContactOptionsResponse, {"data": [_contact_option_payload(contact) for contact in contacts]}, ) @console_ns.route("/workspaces/current/human-input/v2/node-data-migration") class NodeDataMigrationAPI(Resource): @console_ns.doc( description=( "Migrate node data from HITLv1 to HITLv2. " 'A missing legacy version defaults to "1"; any other explicit version is rejected. ' "Every legacy Email recipient becomes onetime_email, while whole_workspace becomes " "all_workspace_contacts. This side-effect-free endpoint only returns migrated node data; " "the caller owns applying it to the Draft workflow." ), ) @console_ns.expect(console_ns.models[NodeDataMigrationPayload.__name__]) @console_ns.response(200, "Success", console_ns.models[NodeDataMigrationResponse.__name__]) @console_ns.response(400, "Migration failed", console_ns.models[NodeDataMigrationFailureResponse.__name__]) @setup_required @login_required @account_initialization_required @edit_permission_required @with_current_tenant_id def post(self, tenant_id: str): request_body = NodeDataMigrationPayload.model_validate(console_ns.payload or {}) outcome = build_human_input_node_data_migration_service().migrate( tenant_id=TenantId(tenant_id), nodes=tuple( MigrationNode.from_preflight( node.node_id, preflight_legacy_human_input_node_data(node.node_data), ) for node in request_body.nodes ), ) if isinstance(outcome, NodeDataMigrationFailure): return ( dump_response( NodeDataMigrationFailureResponse, { "message": "Human Input node-data migration failed.", "blockers": outcome.blockers, }, ), HTTPStatus.BAD_REQUEST, ) return dump_response(NodeDataMigrationResponse, outcome)