notify

type ApprovalCardAction struct {
	Decision string `json:"decision"`
	Title    string `json:"title"`
}

type ApprovalCardFields struct {
	ActionType  string            `json:"action_type"`
	Title       string            `json:"title"`
	Description string            `json:"description"`
	Data        map[string]string `json:"data"`
	// Actions is optional. When omitted, octo-server renders the localized
	// approve/deny buttons (byte-compatible with the pre-http-actions release).
	// When present, it must contain 1..MaxApprovalCustomActions items; each
	// decision is a stable callback token and each title is display text.
	Actions []ApprovalCardAction `json:"actions,omitempty"`
}

type BatchNotifyReq struct {
	Notifications []NotifyReq `json:"notifications" binding:"required"`
}

type BatchNotifyResp struct {
	Results   []BatchNotifyResult `json:"results"`
	HasErrors bool                `json:"has_errors"`
}

type BatchNotifyResult struct {
	NotifyResp
	Error string `json:"error,omitempty"`
}

type CardMutateReq struct {
	SpaceID     string `json:"space_id"`
	ChannelID   string `json:"channel_id"`
	ChannelType uint8  `json:"channel_type"`
	MessageID   string `json:"message_id"`
	Kind        string `json:"kind"` // access_granted | access_denied
	DocID       string `json:"doc_id"`
	Title       string `json:"title"`
	DenyReason  string `json:"deny_reason"` // surfaced on the denied terminal card; empty on approve
	// Older callers may provide operator display context directly. It remains for
	// wire compatibility only and is not authoritative when decider_uid is set.
	//
	// decider_uid/decider_space_id are the AUTHORITATIVE actor ids (mirroring the
	// DecisionResult contract). When present, octo-server resolves the operator
	// name + Space name internally from them and ignores operator_name/
	// operator_space_name below. operator_uid/operator_space_id are older display
	// context fields; they are retained for wire compatibility but are not aliases
	// for, and never substitute for, the authoritative decider identity.
	DeciderUID        string `json:"decider_uid"`
	DeciderSpaceID    string `json:"decider_space_id"`
	OperatorUID       string `json:"operator_uid"`
	OperatorName      string `json:"operator_name"`
	OperatorSpaceID   string `json:"operator_space_id"`
	OperatorSpaceName string `json:"operator_space_name"`
	DecidedAt         int64  `json:"decided_at"`
	DecidedAtDisplay  string `json:"decided_at_display"`
}

type CardMutateResp struct {
	Mutated bool `json:"mutated"`
}

type DeliveredCard struct {
	UID         string `json:"uid"`
	ChannelID   string `json:"channel_id"`
	ChannelType uint8  `json:"channel_type"`
	MessageID   string `json:"message_id"`
	ClientMsgNo string `json:"client_msg_no"`
}

type DocsActionFinalizer struct {
	// contains filtered or unexported fields
}

type DocsCardFields struct {
	DocID     string `json:"doc_id"`     // maps to /d/{doc_id}
	RequestID string `json:"request_id"` // required by access_requested v2; docs domain idempotency/CAS key
	Kind      string `json:"kind"`       // "shared" | "commented" | "access_requested"
	Title     string `json:"title"`      // document title
	ActorName string `json:"actor_name"` // pre-resolved actor display name; empty allowed
	// ActorUID is the requester's uid. When ActorName is empty, octo-server (the
	// identity authority) resolves the display name from it server-side, so the
	// producer need not hold a user-lookup credential. Empty => no resolution.
	ActorUID string `json:"actor_uid"`
	// ActorAvatarURL is an optional absolute https avatar for the requester,
	// surfaced on the access-request approval card. Additive & backward
	// compatible: empty (or omitted) renders no avatar; a non-https value fails
	// the card build (same positive allowlist as any rendered image URL). The
	// docs backend owns population; octo-server does not resolve it.
	ActorAvatarURL string `json:"actor_avatar_url"`
	Excerpt        string `json:"excerpt"` // optional preview / comment / access reason
	// RequesterSpaceName and RequestedBotNames enrich access-request cards only.
	// They are display values resolved by Docs Backend in the requester's Space.
	RequesterSpaceName string   `json:"requester_space_name"`
	RequestedBotNames  []string `json:"requested_bot_names"`
	RequestedRole      string   `json:"requested_role"` // reader | commenter | writer | admin
	UpdatedAt          string   `json:"updated_at"`     // pre-formatted timestamp; empty allowed
}

type Notify struct {
	log.Log
	// contains filtered or unexported fields
}

type NotifyReq struct {
	SpaceID string `json:"space_id" binding:"required"`
	Service string `json:"service" binding:"required"`
	Event   string `json:"event"`
	// Targets is the explicit recipient list. It LOST its binding:"required"
	// tag when target_role was introduced, because binding-level `required`
	// cannot express "exactly one of two fields". The requirement did not go
	// away — it moved into validateTargeting (target_role.go), which is
	// strictly stricter than the old tag: it still rejects an absent/empty
	// `targets` when no role selector is supplied, AND it now also rejects
	// supplying both. A caller that keeps sending `targets` sees no behavioural
	// change whatsoever.
	//
	// That statement is about the single-item POST /v1/internal/notify, which
	// binds a NotifyReq directly. It never applied to /notify/batch: this
	// struct's binding tags were never evaluated for batch entries, because
	// BatchNotifyReq.Notifications carries no `dive` tag and
	// go-playground/validator does not descend into slice elements without one.
	// A batch entry with missing or empty `targets` bound cleanly before and
	// binds cleanly now; it is reported per-item inside a 207. See
	// sendNotifyBatch.
	Targets []string `json:"targets"`
	// TargetRole asks octo-server to resolve the recipients itself from
	// space_member instead of naming them. The only accepted value is
	// TargetRoleSpaceAdmin ("space_admin") = this Space's active owners and
	// admins (role>=1), robots excluded. Empty means "use Targets".
	//
	// Additive + `omitempty`: absent from every request today, and absent from
	// every serialization that does not set it, so the existing docs /
	// bot-mention / summary-card producers are byte-unaffected.
	TargetRole   string                 `json:"target_role,omitempty"`
	ActorUID     string                 `json:"actor_uid"`
	Payload      map[string]interface{} `json:"payload"`
	Card         *SummaryCardFields     `json:"card"`
	DocsCard     *DocsCardFields        `json:"docs_card"`
	ApprovalCard *ApprovalCardFields    `json:"approval_card"`
}

type NotifyResp struct {
	Delivered []string          `json:"delivered"`
	Filtered  map[string]string `json:"filtered"`
	// DeliveredCards carries the IM coordinates of each successfully delivered
	// docs card so a producer can later locate and mutate it in place (docs
	// access-decision card sync, task docs-access-decision-card-sync). Populated
	// only on the docs-card path and only for card (not text-fallback) sends;
	// omitted on legacy/text paths. Additive + omitempty so existing consumers
	// that read only Delivered are unaffected.
	DeliveredCards []DeliveredCard `json:"delivered_cards,omitempty"`
}

type StandardActionFinalizer struct {
	// contains filtered or unexported fields
}

type SummaryCardFields struct {
	TaskNo      string `json:"task_no"`      // summary_task.task_no,用于 /s/{task_no}?sp={space_id}
	Kind        string `json:"kind"`         // "completed" | "failed"
	Title       string `json:"title"`        // 总结标题(服务端转义/截断)
	TimeRange   string `json:"time_range"`   // 已格式化的时间范围;空则省略
	Members     int    `json:"members"`      // 参与人数;<=0 省略
	MsgCount    int    `json:"msg_count"`    // 消息条数;<=0 省略
	GeneratedAt string `json:"generated_at"` // 已格式化的生成时间;空则省略
	Reason      string `json:"reason"`       // failed 的脱敏原因;completed 留空
}