model

type Action string

type ActivityStats struct {
	TotalEvents int             `json:"total_events"`
	Last7d      int             `json:"last_7d"`
	ByActor     []ActorActivity `json:"by_actor"`
}

type Actor struct {
	Name        string    `json:"name"`
	DisplayName string    `json:"display_name"`
	Type        ActorType `json:"type"`
	Role        Role      `json:"role"`
	APIKeyHash  string    `json:"-"`
	CreatedAt   time.Time `json:"created_at"`
	Active      bool      `json:"active"`
}

type ActorActivity struct {
	Name         string `json:"name"`
	EventsLast7d int    `json:"events_last_7d"`
}

type ActorStats struct {
	Total  int            `json:"total"`
	Active int            `json:"active"`
	ByRole map[string]int `json:"by_role"`
}

type ActorType string

type ArchivedError struct {
	BoardSlug string
}

type Attachment struct {
	ID        int       `json:"id"`
	BoardSlug string    `json:"board_slug"`
	TaskNum   int       `json:"task_num"`
	RefType   RefType   `json:"ref_type"`
	Reference string    `json:"reference"`
	Label     string    `json:"label"`
	CreatedBy string    `json:"created_by"`
	CreatedAt time.Time `json:"created_at"`
}

type AuditAction string

type AuditEntry struct {
	ID        int             `json:"id"`
	BoardSlug string          `json:"board_slug"`
	TaskNum   *int            `json:"task_num"` // Nil for board-level events.
	Actor     string          `json:"actor"`    // The actor who performed the action.
	Action    AuditAction     `json:"action"`
	Detail    json.RawMessage `json:"detail"` // Action-specific payload; shape varies by Action.
	CreatedAt time.Time       `json:"created_at"`
}

type Board struct {
	Slug        string          `json:"slug"`
	Name        string          `json:"name"`
	Description string          `json:"description"`
	Workflow    json.RawMessage `json:"workflow"`      // JSON workflow definition; see Workflow struct for schema.
	NextTaskNum int             `json:"next_task_num"` // Auto-increment counter for task numbering on this board.
	CreatedAt   time.Time       `json:"created_at"`
	UpdatedAt   time.Time       `json:"updated_at"`
	Deleted     bool            `json:"deleted"`
}

type BoardDetail struct {
	Board    Board        `json:"board"`
	Workflow any          `json:"workflow"`
	Tasks    []TaskDetail `json:"tasks"`
	Audit    []AuditEntry `json:"audit"`
}

type BoardOverview struct {
	Board
	TaskCounts map[string]int `json:"task_counts"`
	TotalTasks int            `json:"total_tasks"`
}

type BoardStats struct {
	Total  int `json:"total"`
	Active int `json:"active"`
}

type Comment struct {
	ID        int        `json:"id"`
	BoardSlug string     `json:"board_slug"`
	TaskNum   int        `json:"task_num"`
	Actor     string     `json:"actor"` // The actor who wrote the comment (not necessarily the task creator).
	Body      string     `json:"body"`
	CreatedAt time.Time  `json:"created_at"`
	UpdatedAt *time.Time `json:"updated_at"`
}

type ConflictError struct {
	Resource string
	Field    string
	Value    string
	Message  string
}

type CreateActorParams struct {
	Name        string    `json:"name"`
	DisplayName string    `json:"display_name,omitempty"`
	Type        ActorType `json:"type"`
	Role        Role      `json:"role"`
	APIKeyHash  string    `json:"-"`
}

type CreateAttachmentParams struct {
	BoardSlug string  `json:"-"`
	TaskNum   int     `json:"-"`
	RefType   RefType `json:"ref_type"`
	Reference string  `json:"reference"`
	Label     string  `json:"label"`
	CreatedBy string  `json:"-"`
}

type CreateBoardParams struct {
	Slug        string          `json:"slug"`
	Name        string          `json:"name"`
	Description string          `json:"description,omitempty"`
	Workflow    json.RawMessage `json:"workflow,omitempty"`
}

type CreateCommentParams struct {
	BoardSlug string `json:"-"`
	TaskNum   int    `json:"-"`
	Actor     string `json:"-"`
	Body      string `json:"body"`
}

type CreateDependencyParams struct {
	BoardSlug      string         `json:"-"`
	TaskNum        int            `json:"-"`
	DependsOnBoard string         `json:"depends_on_board"`
	DependsOnNum   int            `json:"depends_on_num"`
	DependencyType DependencyType `json:"dep_type"`
	CreatedBy      string         `json:"-"`
}

type CreateTaskParams struct {
	BoardSlug   string     `json:"-"`
	Title       string     `json:"title"`
	Description string     `json:"description,omitempty"`
	Priority    Priority   `json:"priority,omitempty"`
	Tags        []string   `json:"tags,omitempty"`
	Assignee    *string    `json:"assignee"`
	DueDate     *time.Time `json:"due_date"`
	CreatedBy   string     `json:"-"`
}

type CreateWebhookParams struct {
	URL       string   `json:"url"`
	Events    []string `json:"events"`
	BoardSlug *string  `json:"board_slug"`
	Secret    string   `json:"secret"`
	CreatedBy string   `json:"-"`
}

type Dependency struct {
	ID             int            `json:"id"`
	BoardSlug      string         `json:"board_slug"` // Board of the task that has the dependency.
	TaskNum        int            `json:"task_num"`
	DependsOnBoard string         `json:"depends_on_board"` // Board of the depended-on task (may differ for cross-board deps).
	DependsOnNum   int            `json:"depends_on_num"`
	DependencyType DependencyType `json:"dep_type"`
	CreatedBy      string         `json:"created_by"`
	CreatedAt      time.Time      `json:"created_at"`
}

type DependencyType string

type ListBoardsParams struct {
	IncludeDeleted bool `query:"include_deleted,Include soft-deleted boards"`
}

type NotFoundError struct {
	Resource string
	ID       string
}

type Operation struct {
	Name        string // canonical identifier, e.g. "task_create"
	Action      Action // the kind of mutation
	Path        string // resource address pattern: /boards/{slug}/tasks/{num}
	Summary     string // short description (OpenAPI, CLI)
	Description string // longer description with usage guidance (MCP tools)
	MinRole     Role   // minimum role required
	Input       any    // nil, or zero-value of request type (for schema generation)
	Output      any    // nil, or zero-value of response type (for schema generation)
}

type Optional[T any] struct {
	Value T
	Set   bool
}

type PathParam struct {
	Name string
	Type string // "string" or "integer"
}

type Priority string

type QueryParam struct {
	Name string
	Type string // "string", "integer", "boolean"
	Desc string
}

type ReassignRequest struct {
	TargetBoard string   `json:"target_board"`
	States      []string `json:"states,omitempty"`
}

type ReassignResponse struct {
	Count int `json:"count"`
}

type RefType string

type Resource struct {
	Name        string // canonical identifier, e.g. "board_list"
	Path        string // resource address pattern: /boards/{slug}
	Summary     string // short description (OpenAPI, CLI)
	Description string // longer description with usage guidance (MCP tools)
	MinRole     Role   // minimum role required (defaults to RoleReadOnly)
	Output      any    // zero-value of response type (for schema generation)
	Filter      any    // nil, or zero-value of filter struct (query params derived from `query` tags)
	Sort        any    // nil, or zero-value of sort struct (query params derived from `query` tags)
}

type Role string

type SystemStats struct {
	Actors   ActorStats       `json:"actors"`
	Boards   BoardStats       `json:"boards"`
	Tasks    TaskStatsSummary `json:"tasks"`
	Activity ActivityStats    `json:"activity"`
}

type TagCount struct {
	Tag   string `json:"tag"`
	Count int    `json:"count"`
}

type Task struct {
	BoardSlug   string     `json:"board_slug"`
	Num         int        `json:"num"` // Board-scoped sequential identifier (e.g., my-board/42).
	Title       string     `json:"title"`
	Description string     `json:"description"`
	State       string     `json:"state"` // Workflow-defined state; valid values depend on the board's workflow.
	Priority    Priority   `json:"priority"`
	Tags        []string   `json:"tags"`
	Assignee    *string    `json:"assignee"`
	DueDate     *time.Time `json:"due_date"`
	CreatedBy   string     `json:"created_by"`
	CreatedAt   time.Time  `json:"created_at"`
	UpdatedAt   time.Time  `json:"updated_at"`
	Deleted     bool       `json:"deleted"`
}

type TaskDetail struct {
	Task
	Comments     []Comment    `json:"comments"`
	Attachments  []Attachment `json:"attachments"`
	Dependencies []Dependency `json:"dependencies"`
	Audit        []AuditEntry `json:"audit"`
}

type TaskFilter struct {
	BoardSlug      string    // path param, not a query param
	State          *string   `query:"state,Filter by workflow state"`
	Assignee       *string   `query:"assignee,Filter by assignee name"`
	Priority       *Priority `query:"priority,Filter by priority (critical/high/medium/low/none)"`
	Tag            *string   `query:"tag,Filter by tag"`
	Query          *string   `query:"q,Full-text search query"`
	IncludeClosed  bool      `query:"include_closed,Include tasks in terminal states"`
	IncludeDeleted bool      `query:"include_deleted,Include soft-deleted tasks"`
}

type TaskSort struct {
	Field string `query:"sort,Sort field (created_at/updated_at/priority/due_date)"`
	Desc  bool   `query:"order,string,Sort order (asc/desc)"`
}

type TaskStatsSummary struct {
	Total           int            `json:"total"`
	ByState         map[string]int `json:"by_state"`
	CreatedLast7d   int            `json:"created_last_7d"`
	CompletedLast7d int            `json:"completed_last_7d"`
}

type TransitionTaskParams struct {
	BoardSlug      string `json:"-"`
	Num            int    `json:"-"`
	TransitionName string `json:"transition"`
	Comment        string `json:"comment,omitempty"`
	Actor          string `json:"-"`
}

type UpdateActorParams struct {
	Name        string           `json:"-"`
	DisplayName Optional[string] `json:"display_name"`
	Role        Optional[Role]   `json:"role"`
	Active      Optional[bool]   `json:"active"`
}

type UpdateBoardParams struct {
	Slug        string           `json:"-"`
	Name        Optional[string] `json:"name"`
	Description Optional[string] `json:"description"`
}

type UpdateCommentParams struct {
	ID   int    `json:"-"`
	Body string `json:"body"`
}

type UpdateTaskParams struct {
	BoardSlug   string               `json:"-"`
	Num         int                  `json:"-"`
	Title       Optional[string]     `json:"title"`
	Description Optional[string]     `json:"description"`
	State       Optional[string]     `json:"state"`
	Priority    Optional[Priority]   `json:"priority"`
	Tags        Optional[[]string]   `json:"tags"`
	Assignee    Optional[*string]    `json:"assignee"` // Set with nil value clears the assignee.
	DueDate     Optional[*time.Time] `json:"due_date"` // Set with nil value clears the due date.
}

type UpdateWebhookParams struct {
	ID     int                `json:"-"`
	URL    Optional[string]   `json:"url"`
	Events Optional[[]string] `json:"events"`
	Active Optional[bool]     `json:"active"`
}

type ValidationError struct {
	Field   string
	Message string
	Detail  any
}

type Webhook struct {
	ID        int       `json:"id"`
	URL       string    `json:"url"`
	Events    []string  `json:"events"`     // Event types to subscribe to (e.g., "task.created", "task.transitioned").
	BoardSlug *string   `json:"board_slug"` // Nil means all boards.
	Secret    string    `json:"-"`          // Shared secret for HMAC-SHA256 webhook signatures.
	Active    bool      `json:"active"`
	CreatedBy string    `json:"created_by"`
	CreatedAt time.Time `json:"created_at"`
	UpdatedAt time.Time `json:"updated_at"`
}

type WebhookDelivery struct {
	ID          int       `json:"id"`
	WebhookID   int       `json:"webhook_id"`
	EventType   string    `json:"event_type"`
	EventID     string    `json:"event_id"`
	Attempt     int       `json:"attempt"`
	StatusCode  *int      `json:"status_code"` // nil if request failed before response
	Error       *string   `json:"error"`       // nil on success
	RequestBody string    `json:"-"`           // not exposed in API responses
	DurationMs  *int      `json:"duration_ms"`
	CreatedAt   time.Time `json:"created_at"`
}

type Workflow struct {
	States         []string             `json:"states"`
	InitialState   string               `json:"initial_state"`
	TerminalStates []string             `json:"terminal_states"`
	Transitions    []WorkflowTransition `json:"transitions"`
	FromAll        []WorkflowFromAll    `json:"from_all,omitempty"` // Transitions reachable from every non-terminal state.
	ToAll          []WorkflowToAll      `json:"to_all,omitempty"`   // Transitions from a specific state to every other state.
}

type WorkflowFromAll struct {
	To   string `json:"to"`
	Name string `json:"name"`
}

type WorkflowHealthIssue struct {
	State   string `json:"state"`
	Problem string `json:"problem"` // "orphaned" or "stuck"
	Count   int    `json:"count"`
}

type WorkflowToAll struct {
	From string `json:"from"`
	Name string `json:"name"`
}

type WorkflowTransition struct {
	From string `json:"from"`
	To   string `json:"to"`
	Name string `json:"name"`
}