conversationep

type AddConversationLinkEndpoint struct{}

type AddConversationLinkRequest struct {
	// Conversation ID.
	ConversationID string `path:"id" validate:"required"`
	// The kind of business record to link.
	ResourceType constants.ObjectType `json:"resource_type" validate:"required"`
	// The id of the business record to link.
	ResourceID string `json:"resource_id" validate:"required"`
}

type ArchiveConversationEndpoint struct{}

type ArchiveConversationRequest struct {
	// Conversation ID.
	ConversationID string `path:"id" validate:"required"`
}

type AssignConversationEndpoint struct{}

type AssignConversationRequest struct {
	// Conversation ID.
	ConversationID string `path:"id" validate:"required"`
	// What kind of owner the case is being assigned to.
	//
	// - `account_user`: an individual teammate takes the case.
	// - `account_group`: a team takes the case, so anyone on it can pick it up.
	AssigneeResourceType field.Optional[constants.ConversationAssigneeType] `json:"assignee_resource_type,omitzero"`
	// The owner's id, an `account_user` or `account_group` matching `assignee_resource_type`.
	//
	// Omit this and `assignee_resource_type` to clear the assignment.
	AssigneeResourceID field.Optional[string] `json:"assignee_resource_id,omitzero"`
}

type ContactSupportEndpoint struct{}

type ContactSupportRequest struct{}

type ConversationSvc interface {
	CreateConversation(ctx context.Context, req *CreateConversationRequest) (*apiresource.Conversation, *apierror.APIError)
	ListConversations(ctx context.Context, req *ListConversationsRequest) (*apiresource.List[apiresource.Conversation], *apierror.APIError)
	GetConversation(ctx context.Context, req *RetrieveConversationRequest) (*apiresource.Conversation, *apierror.APIError)
	ContactSupport(ctx context.Context, req *ContactSupportRequest) (*apiresource.Conversation, *apierror.APIError)
	SupportAvailability(ctx context.Context, req *SupportAvailabilityRequest) (*apiresource.SupportAvailability, *apierror.APIError)
	MarkConversationRead(ctx context.Context, req *MarkConversationReadRequest) (*apiresource.Conversation, *apierror.APIError)
	UpdateConversation(ctx context.Context, req *UpdateConversationRequest) (*apiresource.Conversation, *apierror.APIError)
	ArchiveConversation(ctx context.Context, req *ArchiveConversationRequest) (*apiresource.Conversation, *apierror.APIError)
	UnarchiveConversation(ctx context.Context, req *UnarchiveConversationRequest) (*apiresource.Conversation, *apierror.APIError)
	LeaveConversation(ctx context.Context, req *LeaveConversationRequest) (*apiresource.Conversation, *apierror.APIError)
	HideConversation(ctx context.Context, req *HideConversationRequest) (*apiresource.Conversation, *apierror.APIError)
	UnhideConversation(ctx context.Context, req *UnhideConversationRequest) (*apiresource.Conversation, *apierror.APIError)
	MuteConversation(ctx context.Context, req *MuteConversationRequest) (*apiresource.Conversation, *apierror.APIError)
	UnmuteConversation(ctx context.Context, req *UnmuteConversationRequest) (*apiresource.Conversation, *apierror.APIError)
	SendTyping(ctx context.Context, req *TypingRequest) (*apiresource.MessageResource, *apierror.APIError)
	SetLegalHold(ctx context.Context, req *SetLegalHoldRequest) (*apiresource.Conversation, *apierror.APIError)
	RedactConversation(ctx context.Context, req *RedactConversationRequest) (*apiresource.Conversation, *apierror.APIError)
	// External customer-service cases: triage, assignment, links, report.
	SetWorkflowStatus(ctx context.Context, req *SetWorkflowStatusRequest) (*apiresource.Conversation, *apierror.APIError)
	AssignConversation(ctx context.Context, req *AssignConversationRequest) (*apiresource.Conversation, *apierror.APIError)
	ReportConversation(ctx context.Context, req *ReportConversationRequest) (*apiresource.Conversation, *apierror.APIError)
	AddConversationLink(ctx context.Context, req *AddConversationLinkRequest) (*apiresource.ConversationLink, *apierror.APIError)
	RemoveConversationLink(ctx context.Context, req *RemoveConversationLinkRequest) (*apiresource.EmptyResource, *apierror.APIError)
	ListConversationLinks(ctx context.Context, req *ListConversationLinksRequest) (*apiresource.List[apiresource.ConversationLink], *apierror.APIError)
}

type ConversationSvcConfig struct {
	// ChatClient (required) is the notification-service ChatService gRPC client.
	ChatClient pb.ChatServiceClient
}

type CreateConversationEndpoint struct{}

type CreateConversationRequest struct {
	// The kind of conversation to create.
	//
	// - `direct_message`: a 1:1 thread with exactly one other user. Addressing yourself is allowed and gives you a private notes thread.
	// - `group`: a named thread with any number of user and agent members.
	//
	// `system` channels are created by the platform and cannot be requested here.
	Type constants.ConversationType `json:"type" validate:"required"`
	// The other participants to add.
	//
	// For a direct message, exactly one account user. For a group, the members to seed — these can be omitted when `group_id` supplies a roster, or when the conversation is anchored to a topic resource, since a record discussion may start solo and pull people in later.
	//
	// The caller is always a participant and does not need to be listed; on a group they become its owner and every other member seeded at creation is notified.
	ParticipantAccountUserIDs []string `json:"participant_account_user_ids,omitzero" validate:"omitempty,dive,required"`
	// Seed a group conversation from a reusable roster.
	//
	// The roster's current members are copied into this conversation (in addition to any `participant_account_user_ids`); the conversation is independent afterward. Ignored for direct messages.
	GroupID field.Optional[string] `json:"group_id,omitzero"`
	// Title for a group conversation.
	//
	// A direct message is identified by its participants rather than by a title.
	Title field.Optional[string] `json:"title,omitzero"`
	// The type of business record to anchor this conversation to.
	//
	// An anchored conversation is returned when conversations are listed for that record, which is how a discussion shows up on an order or invoice.
	TopicResourceType field.Optional[constants.ObjectType] `json:"topic_resource_type,omitzero"`
	// The id of the business record to anchor this conversation to.
	TopicResourceID field.Optional[string] `json:"topic_resource_id,omitzero"`
}

type HideConversationEndpoint struct{}

type HideConversationRequest struct {
	// Conversation ID.
	ConversationID string `path:"id" validate:"required"`
}

type LeaveConversationEndpoint struct{}

type LeaveConversationRequest struct {
	// Conversation ID.
	ConversationID string `path:"id" validate:"required"`
}

type ListConversationLinksEndpoint struct{}

type ListConversationLinksRequest struct {
	// Conversation ID.
	ConversationID string `path:"id" validate:"required"`
}

type ListConversationsEndpoint struct{}

type ListConversationsRequest struct {
	apiresource.PaginationRequest
	// Filter by conversation type.
	Type *constants.ConversationType `query:"type"`
	// Filter by whether the conversation is team-only or customer-facing.
	//
	// - `internal`: threads the customer never sees — direct messages, group threads, and record discussions.
	// - `customer`: external customer-service cases the customer takes part in, from the portal or a bridged email thread.
	Audience *constants.ConversationAudience `query:"audience"`
	// Filter by whether the caller has hidden the conversation from their own list.
	Status *constants.ConversationListStatus `query:"status" default:"active"`
	// Restrict to conversations attached to a business record of this type, together with `topic_resource_id`.
	//
	// Matches both conversations anchored to the record and conversations that merely link it, which is what powers the "discussions on this record" view.
	TopicResourceType *constants.ObjectType `query:"topic_resource_type"`
	// The id of the business record, together with `topic_resource_type`.
	TopicResourceID *string `query:"topic_resource_id"`
	// Filter the support inbox to a single triage lane.
	//
	// - `new`: opened but nobody has triaged it yet.
	// - `open`: actively being worked.
	// - `waiting_internal`: blocked on the internal team.
	// - `waiting_external`: blocked on a reply from the customer.
	// - `needs_approval`: a drafted reply is waiting for a human to approve it.
	// - `resolved`: closed out.
	//
	// The working inbox hides resolved cases unless you ask for this lane explicitly.
	WorkflowStatus *constants.ConversationWorkflowStatus `query:"workflow_status"`
	// Filter the support inbox to cases owned by this assignee, an account user or an account group.
	AssigneeResourceID *string `query:"assignee_resource_id"`
	// Restrict the support inbox to cases nobody has been assigned yet.
	Unassigned bool `query:"unassigned"`
	// Return the archived support inbox instead of the working one.
	//
	// This swaps the view rather than widening it: archived cases are returned and unarchived ones are left out.
	IncludeArchived bool `query:"include_archived"`
}

type MarkConversationReadEndpoint struct{}

type MarkConversationReadRequest struct {
	// Conversation ID.
	ConversationID string `path:"id" validate:"required"`
	// Mark every message up to and including this sequence number as read.
	//
	// A sequence past the conversation's latest message is clamped to it, and the read position never moves backwards, so replaying an older value is harmless.
	UpToSequence int64 `json:"up_to_sequence" validate:"required"`
}

type MuteConversationEndpoint struct{}

type MuteConversationRequest struct {
	// Conversation ID.
	ConversationID string `path:"id" validate:"required"`
	// When the mute expires.
	//
	// Omit to mute indefinitely.
	MutedUntil field.Optional[time.Time] `json:"muted_until,omitzero"`
}

type RedactConversationEndpoint struct{}

type RedactConversationRequest struct {
	// Conversation ID.
	ConversationID string `path:"id" validate:"required"`
}

type RemoveConversationLinkEndpoint struct{}

type RemoveConversationLinkRequest struct {
	// Conversation ID.
	ConversationID string `path:"id" validate:"required"`
	// The id of the link to remove.
	LinkID string `path:"link_id" validate:"required"`
}

type ReportConversationEndpoint struct{}

type ReportConversationRequest struct {
	// Conversation ID.
	ConversationID string `path:"id" validate:"required"`
	// Why the conversation or message is being reported, in free-form text.
	Reason string `json:"reason" validate:"required"`
	// The specific message being reported.
	//
	// Omit to report the conversation as a whole.
	MessageID field.Optional[string] `json:"message_id,omitzero"`
}

type RetrieveConversationEndpoint struct{}

type RetrieveConversationRequest struct {
	// Conversation ID.
	ConversationID string `path:"id" validate:"required"`
}

type SetLegalHoldEndpoint struct{}

type SetLegalHoldRequest struct {
	// Conversation ID.
	ConversationID string `path:"id" validate:"required"`
	// Whether to place the conversation under legal hold or release it.
	//
	// - `held`: the conversation is preserved — exempt from automatic retention purging and from redaction.
	// - `released`: normal retention and redaction apply again.
	LegalHold constants.LegalHoldStatus `json:"legal_hold" validate:"required"`
}

type SetWorkflowStatusEndpoint struct{}

type SetWorkflowStatusRequest struct {
	// Conversation ID.
	ConversationID string `path:"id" validate:"required"`
	// The triage lane to move the case to.
	//
	// - `new`: opened but nobody has triaged it yet.
	// - `open`: actively being worked.
	// - `waiting_internal`: blocked on the internal team.
	// - `waiting_external`: blocked on a reply from the customer.
	// - `needs_approval`: a drafted reply is waiting for a human to approve it.
	// - `resolved`: closed out.
	WorkflowStatus constants.ConversationWorkflowStatus `json:"workflow_status" validate:"required"`
}

type SupportAvailabilityEndpoint struct{}

type SupportAvailabilityRequest struct{}

type TypingEndpoint struct{}

type TypingRequest struct {
	// Conversation ID.
	ConversationID string `path:"id" validate:"required"`
}

type UnarchiveConversationEndpoint struct{}

type UnarchiveConversationRequest struct {
	// Conversation ID.
	ConversationID string `path:"id" validate:"required"`
}

type UnhideConversationEndpoint struct{}

type UnhideConversationRequest struct {
	// Conversation ID.
	ConversationID string `path:"id" validate:"required"`
}

type UnmuteConversationEndpoint struct{}

type UnmuteConversationRequest struct {
	// Conversation ID.
	ConversationID string `path:"id" validate:"required"`
}

type UpdateConversationEndpoint struct{}

type UpdateConversationRequest struct {
	// Conversation ID.
	ConversationID string `path:"id" validate:"required"`
	// The group conversation's new display title.
	//
	// Send `null` to clear the title and leave the conversation unnamed.
	Title field.Clearable[string] `json:"title,omitzero"`
}