provider

type AddCollaboratorOptions struct {
	Permission string `json:"permission,omitempty"` // "read", "write", "admin"
}

type AddDeployKeyOptions struct {
	Title    string `json:"title"`
	Key      string `json:"key"`
	ReadOnly bool   `json:"read_only,omitempty"`
}

type BatchOptions struct {
	// Concurrency is the maximum number of in-flight operations;
	// defaults to DefaultBatchConcurrency, capped at
	// MaxBatchConcurrency.
	Concurrency int
}

type BatchResult[T any] struct {
	// Key is the input selector: the file path, CR number, or the
	// status context.
	Key string
	// Value carries the operation result when Err is nil.
	Value T
	// Err is the per-item failure, already wrapped as a provider error
	// by the underlying call.
	Err error
}

type BranchManager interface {
	ListBranches(ctx context.Context, owner, repo string) ([]*PlatformBranch, error)
	CreateBranch(ctx context.Context, owner, repo, branch, ref string) (*PlatformBranch, error)
	DeleteBranch(ctx context.Context, owner, repo, branch string) error
}

type BranchProtection struct {
	BranchName               string `json:"branch_name"`
	RequiredApprovingReviews int    `json:"required_approving_reviews"`
	RequiredStatusChecks     bool   `json:"required_status_checks"`
	AllowForcePushes         bool   `json:"allow_force_pushes"`
	AllowDeletions           bool   `json:"allow_deletions"`
}

type BranchProtectionManager interface {
	// ListBranchProtections returns all branch protection rules for a repo.
	ListBranchProtections(ctx context.Context, owner, repo string) ([]*BranchProtection, error)
	// GetBranchProtection returns the protection rule for a specific branch.
	GetBranchProtection(ctx context.Context, owner, repo, branch string) (*BranchProtection, error)
	// CreateBranchProtection creates a new branch protection rule.
	CreateBranchProtection(ctx context.Context, owner, repo string, opts CreateBranchProtectionOptions) (*BranchProtection, error)
	// UpdateBranchProtection updates an existing branch protection rule.
	UpdateBranchProtection(ctx context.Context, owner, repo, branch string, opts UpdateBranchProtectionOptions) (*BranchProtection, error)
	// DeleteBranchProtection removes the protection rule for a branch.
	DeleteBranchProtection(ctx context.Context, owner, repo, branch string) error
}

type CILogManager interface {
	// ListFailedJobLogs returns the failed jobs of the most recent pipeline
	// for a commit, each with the tail of its execution log. A commit with
	// no pipeline (or a green one) yields an empty slice, not an error.
	ListFailedJobLogs(ctx context.Context, owner, repo, sha string) ([]JobLog, error)
}

type CRComment struct {
	ID        int64     `json:"id"`
	Body      string    `json:"body"`
	Author    *CRUser   `json:"author"`
	CreatedAt time.Time `json:"created_at"`
	UpdatedAt time.Time `json:"updated_at"`
}

type CRCommit struct {
	SHA       string    `json:"sha"`
	Message   string    `json:"message"`
	Author    *CRUser   `json:"author"`
	CreatedAt time.Time `json:"created_at"`
}

type CRState string

type CRUser struct {
	ID        int64  `json:"id"`
	Username  string `json:"username"`
	Name      string `json:"name"`
	AvatarURL string `json:"avatar_url"`
}

type CapabilitySet struct {
	Issues            bool // provider.IssueManager
	Search            bool // provider.SearchManager
	Labels            bool // provider.LabelManager
	Milestones        bool // provider.MilestoneManager
	Reviews           bool // provider.ReviewManager
	CommitStatuses    bool // provider.CommitStatusManager
	Notifications     bool // provider.NotificationManager
	Reactions         bool // provider.ReactionManager
	BranchProtections bool // provider.BranchProtectionManager
	Collaborators     bool // provider.CollaboratorManager
	WebhookConfig     bool // provider.WebhookConfigManager
	DeployKeys        bool // provider.DeploymentKeyManager
	RepoStats         bool // provider.RepoStatsManager
	Users             bool // provider.UserManager
	Gists             bool // provider.GistManager
	Starred           bool // provider.StarredManager
	Migrations        bool // provider.MigrationManager
	ReleaseAssets     bool // provider.ReleaseAssetManager
}

type ChangeRequest struct {
	ID           int64   `json:"id"`
	Number       string  `json:"number"`
	Title        string  `json:"title"`
	Description  string  `json:"description"`
	State        CRState `json:"state"`
	SourceBranch string  `json:"source_branch"`
	TargetBranch string  `json:"target_branch"`
	// HeadSHA is the SHA of the source-branch tip.
	// BaseSHA is the diff base: the merge-base (common ancestor) where GitLab/TencentCode
	// expose it via diff_refs.base_sha. GitHub/Gitea do not expose a distinct merge base in
	// webhook payloads, so BaseSHA there is the target-branch tip (equivalent to StartSHA).
	// StartSHA is the SHA of the target-branch tip at event time (GitLab diff_refs.start_sha).
	// On GitHub/Gitea it equals BaseSHA since no separate value is exposed.
	HeadSHA  string `json:"head_sha,omitempty"`
	BaseSHA  string `json:"base_sha,omitempty"`
	StartSHA string `json:"start_sha,omitempty"`
	// Draft reports the work-in-progress / draft state uniformly across platforms
	// (GitHub pr.draft, Gitea draft, GitLab/TencentCode work_in_progress).
	Draft       bool      `json:"draft"`
	Author      *CRUser   `json:"author"`
	Assignees   []*CRUser `json:"assignees,omitempty"`
	Reviewers   []*CRUser `json:"reviewers"`
	Labels      []string  `json:"labels"`
	MergeStatus string    `json:"merge_status"`
	WebURL      string    `json:"web_url"`
	CreatedAt   time.Time `json:"created_at"`
	UpdatedAt   time.Time `json:"updated_at"`
}

type ChangeRequestManager interface {
	CreateCR(ctx context.Context, opts CreateCROptions) (*ChangeRequest, error)
	GetCR(ctx context.Context, owner, repo, number string) (*ChangeRequest, error)
	// ListCRs lists change requests. total is nil when the platform
	// provided no authoritative total for the page (an unknown count is
	// reported as unknown, never as the page length); a non-nil total is
	// the platform's own metadata (exact or header-derived).
	ListCRs(ctx context.Context, opts ListCROptions) ([]*ChangeRequest, *int, error)
	MergeCR(ctx context.Context, owner, repo, number string, opts MergeCROptions) (*ChangeRequest, error)
	CloseCR(ctx context.Context, owner, repo, number string) (*ChangeRequest, error)
	ReopenCR(ctx context.Context, owner, repo, number string) (*ChangeRequest, error)
	UpdateCR(ctx context.Context, owner, repo, number string, opts UpdateCROptions) (*ChangeRequest, error)
	UpdateCRLabels(ctx context.Context, owner, repo, number string, labels []string) error
	ListCRComments(ctx context.Context, owner, repo, number string) ([]*CRComment, error)
	ListCRCommits(ctx context.Context, owner, repo, number string) ([]*CRCommit, error)
}

type ChangedFile struct {
	OldPath   string `json:"old_path"`
	NewPath   string `json:"new_path"`
	Diff      string `json:"diff"`
	Additions int    `json:"additions"`
	Deletions int    `json:"deletions"`
	IsNew     bool   `json:"new_file"`
	IsDeleted bool   `json:"deleted_file"`
	IsRenamed bool   `json:"renamed_file"`
	IsBinary  bool   `json:"binary"`
}

type Collaborator struct {
	ID         int64   `json:"id"`
	Username   string  `json:"username"`
	Permission string  `json:"permission,omitempty"`
	User       *CRUser `json:"user,omitempty"`
}

type CollaboratorManager interface {
	// ListCollaborators returns all collaborators on a repository.
	ListCollaborators(ctx context.Context, owner, repo string) ([]*Collaborator, error)
	// AddCollaborator adds a user as a collaborator. Permission is
	// platform-specific ("read", "write", "admin"; empty = default).
	AddCollaborator(ctx context.Context, owner, repo, username string, opts AddCollaboratorOptions) error
	// RemoveCollaborator removes a user from the repository.
	RemoveCollaborator(ctx context.Context, owner, repo, username string) error
}

type CombinedCommitStatus struct {
	State CommitStatusState `json:"state"`
	// Contexts maps each contributing context to its latest state.
	Contexts map[string]CommitStatusState `json:"contexts,omitempty"`
}

type CommitInfo struct {
	SHA       string    `json:"sha"`
	Message   string    `json:"message"`
	Author    *CRUser   `json:"author"`
	Committer *CRUser   `json:"committer"`
	CreatedAt time.Time `json:"created_at"`
	Additions int       `json:"additions"`
	Deletions int       `json:"deletions"`
}

type CommitManager interface {
	GetCommit(ctx context.Context, owner, repo, sha string) (*CommitInfo, error)
	ListCommits(ctx context.Context, owner, repo string, opts ListCommitsOptions) ([]*CommitInfo, error)
	CompareCommits(ctx context.Context, owner, repo, base, head string) (*CompareResult, error)
}

type CommitStatus struct {
	State       CommitStatusState `json:"state"`
	Context     string            `json:"context"`
	Description string            `json:"description,omitempty"`
	TargetURL   string            `json:"target_url,omitempty"`
}

type CommitStatusManager interface {
	CreateCommitStatus(ctx context.Context, owner, repo, sha string, opts CommitStatusOptions) error
	// ListCommitStatuses returns the statuses reported on a commit,
	// newest first (the platforms' native order). State is normalized
	// into the CommitStatusState vocabulary by the backend.
	ListCommitStatuses(ctx context.Context, owner, repo, sha string) ([]CommitStatus, error)
}

type CommitStatusOptions struct {
	State       string `json:"state"`
	Context     string `json:"context"`
	Description string `json:"description,omitempty"`
	TargetURL   string `json:"target_url,omitempty"`
}

type CommitStatusState string

type CompareResult struct {
	Commits      []*CommitInfo  `json:"commits"`
	Files        []*ChangedFile `json:"files"`
	TotalCommits int            `json:"total_commits"`
	AheadBy      int            `json:"ahead_by"`
	BehindBy     int            `json:"behind_by"`
}

type Config struct {
	Platform Platform
	BaseURL  string
	Token    string
	SkipTLS  bool

	// TokenSource, when non-nil, supplies the access token on every
	// request through the transport layer and takes precedence over Token.
	// Use it for credentials that rotate or expire (GitHub App installation
	// tokens, OAuth flows); see the TokenSource interface. Static tokens
	// keep using Token.
	TokenSource TokenSource

	// ConditionalRequests enables HTTP conditional requests for GETs: the
	// transport caches responses keyed by their ETag, sends If-None-Match
	// on re-reads, and replays the cached body when the platform answers
	// 304. On platforms that meter 304s favorably (GitHub) this raises
	// sustainable polling rates for wait-for-CI style workloads. Off by
	// default; see transport.ETagCache for the exact semantics.
	ConditionalRequests bool

	// TokenStyle overrides the default authentication header style.
	// Supported values: "private" (PRIVATE-TOKEN, default for GitLab),
	// "bearer" (Authorization: Bearer). Empty string uses platform default.
	TokenStyle string

	// Logger for provider operations. Defaults to a no-op logger.
	Logger Logger
	// RetryConfig for automatic retry on transient failures. nil means no retry.
	RetryConfig *RetryConfig
	// Hooks for request/response lifecycle interception.
	Hooks *Hooks
}

type Contributor struct {
	Username      string `json:"username"`
	Contributions int    `json:"contributions"`
}

type CreateBranchProtectionOptions struct {
	BranchName               string `json:"branch_name"`
	RequiredApprovingReviews int    `json:"required_approving_reviews,omitempty"`
	RequiredStatusChecks     bool   `json:"required_status_checks,omitempty"`
	AllowForcePushes         bool   `json:"allow_force_pushes,omitempty"`
	AllowDeletions           bool   `json:"allow_deletions,omitempty"`
}

type CreateCROptions struct {
	Owner              string   `json:"owner"`
	Repo               string   `json:"repo"`
	Title              string   `json:"title"`
	Description        string   `json:"description,omitempty"`
	SourceBranch       string   `json:"source_branch"`
	TargetBranch       string   `json:"target_branch"`
	Labels             []string `json:"labels,omitempty"`
	RemoveSourceBranch bool     `json:"remove_source_branch,omitempty"`
}

type CreateIssueOptions struct {
	Owner     string   `json:"owner"`
	Repo      string   `json:"repo"`
	Title     string   `json:"title"`
	Body      string   `json:"body,omitempty"`
	Assignees []string `json:"assignees,omitempty"`
	Labels    []string `json:"labels,omitempty"`
	Milestone string   `json:"milestone,omitempty"` // milestone number/ID as a string; "" = do not set
}

type CreateLabelOptions struct {
	Name        string `json:"name"`
	Color       string `json:"color"`
	Description string `json:"description,omitempty"`
}

type CreateMigrationOptions struct {
	// LockRepositories 迁移期间锁定仓库(防止导出过程中数据变动)。
	LockRepositories bool `json:"lock_repositories"`
	// ExcludeMetadata 跳过 issues/PR 等元数据、只导出仓库内容。
	ExcludeMetadata bool `json:"exclude_metadata"`
}

type CreateMilestoneOptions struct {
	Title       string     `json:"title"`
	Description string     `json:"description,omitempty"`
	DueOn       *time.Time `json:"due_on,omitempty"`
}

type CreateReleaseOptions struct {
	TagName    string `json:"tag_name"`
	Target     string `json:"target,omitempty"`
	Title      string `json:"title"`
	Body       string `json:"body,omitempty"`
	Draft      bool   `json:"draft,omitempty"`
	Prerelease bool   `json:"prerelease,omitempty"`
}

type CreateRepoOptions struct {
	Name          string `json:"name"`
	Description   string `json:"description,omitempty"`
	Private       bool   `json:"private,omitempty"`
	AutoInit      bool   `json:"auto_init,omitempty"`
	DefaultBranch string `json:"default_branch,omitempty"`
}

type CreateReviewOptions struct {
	CommitID string          `json:"commit_id,omitempty"`
	Event    string          `json:"event,omitempty"`
	Body     string          `json:"body,omitempty"`
	Comments []ReviewComment `json:"comments,omitempty"`
}

type CreateWebhookOptions struct {
	Owner  string   `json:"owner"`
	Repo   string   `json:"repo"`
	URL    string   `json:"url"`
	Secret string   `json:"secret,omitempty"`
	Events []string `json:"events,omitempty"`
}

type DeployKey struct {
	ID       int64  `json:"id"`
	Title    string `json:"title"`
	Key      string `json:"key"`
	ReadOnly bool   `json:"read_only"`
}

type DeploymentKeyManager interface {
	// ListDeployKeys returns all deploy keys for a repository.
	ListDeployKeys(ctx context.Context, owner, repo string) ([]*DeployKey, error)
	// AddDeployKey adds a new deploy key to the repository.
	AddDeployKey(ctx context.Context, owner, repo string, opts AddDeployKeyOptions) (*DeployKey, error)
	// DeleteDeployKey removes a deploy key by its platform ID.
	DeleteDeployKey(ctx context.Context, owner, repo string, keyID int64) error
}

type DetectResult struct {
	Platform Platform
	Owner    string
	Repo     string
	BaseURL  string
}

type DiffManager interface {
	GetCRDiff(ctx context.Context, owner, repo, number string) (*MergeDiff, error)
	GetCRFiles(ctx context.Context, owner, repo, number string) ([]*ChangedFile, error)
	CreateNote(ctx context.Context, owner, repo, number, body string) (string, error)
	DeleteNote(ctx context.Context, owner, repo, number string, noteID string) error
	CreateDiscussion(ctx context.Context, owner, repo, number string, opts DiscussionOptions) (string, error)
}

type DiscussionOptions struct {
	Body         string `json:"body"`
	FilePath     string `json:"file_path,omitempty"`
	NewLine      int    `json:"new_line,omitempty"`
	OldLine      int    `json:"old_line,omitempty"`
	StartNewLine int    `json:"start_new_line,omitempty"`
	BaseSHA      string `json:"base_sha,omitempty"`
	StartSHA     string `json:"start_sha,omitempty"`
	HeadSHA      string `json:"head_sha,omitempty"`
}

type Divergence struct {
	Capability string
	Method     string
	Field      string
	Kind       DivergenceKind
	Reason     string
}

type DivergenceKind string

type EnsureAction string

type EventRepo struct {
	ID       int64  `json:"id"`
	FullName string `json:"full_name"`
	Owner    string `json:"owner"`
	Name     string `json:"name"`
}

type FileDeleteOptions struct {
	Path    string `json:"path"`
	Message string `json:"message"`
	Branch  string `json:"branch,omitempty"`
	SHA     string `json:"sha,omitempty"`
	Author  string `json:"author,omitempty"`
	Email   string `json:"email,omitempty"`
}

type FileManager interface {
	GetFileContent(ctx context.Context, owner, repo, path, ref string) (string, error)
	CreateFile(ctx context.Context, owner, repo string, opts FileOptions) (*FileResult, error)
	UpdateFile(ctx context.Context, owner, repo string, opts FileOptions) (*FileResult, error)
	DeleteFile(ctx context.Context, owner, repo string, opts FileDeleteOptions) (*FileResult, error)
}

type FileOptions struct {
	Path    string `json:"path"`
	Content string `json:"content"`
	Message string `json:"message"`
	Branch  string `json:"branch,omitempty"`
	SHA     string `json:"sha,omitempty"`
	Author  string `json:"author,omitempty"`
	Email   string `json:"email,omitempty"`
}

type FileResult struct {
	SHA       string `json:"sha,omitempty"`
	CommitSHA string `json:"commit_sha,omitempty"`
}

type ForgejoWebhookValidator struct{}

type ForkRepoOptions struct {
	Organization string `json:"organization,omitempty"`
	Name         string `json:"name,omitempty"`
}

type Gist struct {
	ID          string              `json:"id"`
	Description string              `json:"description"`
	Public      bool                `json:"public"`
	HTMLURL     string              `json:"html_url"`
	CreatedAt   time.Time           `json:"created_at"`
	UpdatedAt   time.Time           `json:"updated_at"`
	Files       map[string]GistFile `json:"files"`
}

type GistFile struct {
	Filename string `json:"filename"`
	Language string `json:"language"`
	RawURL   string `json:"raw_url"`
	Size     int64  `json:"size"`
	Content  string `json:"content"`
}

type GistManager interface {
	// ListMyGists 分页列出 token 用户可见的 gist(GET /gists:已认证调用
	// 返回当前用户的 gist 列表)。page/perPage 语义与其他分页方法一致,
	// 非法值经 NormalizePageOpts 归一。
	ListMyGists(ctx context.Context, page, perPage int) ([]*Gist, error)
}

type GitCodeWebhookValidator struct{}

type GiteeWebhookValidator struct {
	// MaxAge bounds |now - X-Gitee-Timestamp| in sign mode. Zero means
	// DefaultGiteeSignMaxAge; a negative value disables the freshness
	// check (not recommended — it enables indefinite replay).
	MaxAge time.Duration
	// AllowPasswordMode also accepts the plain-password form when
	// X-Gitee-Timestamp is absent. Enable only when the webhook is known
	// to be configured in password mode.
	AllowPasswordMode bool
}

type HMACSHA256Validator struct {
	Header string
}

type HmacValidator struct {
	Header    string
	Algorithm string // "sha1", "sha256", "sha512"
	Prefix    string // expected signature prefix ("sha256=")
}

type Hooks struct {
	Request  []RequestHook
	Response []ResponseHook
}

type Issue struct {
	ID        int64         `json:"id"`
	Number    string        `json:"number"`
	Title     string        `json:"title"`
	Body      string        `json:"body"`
	State     IssueState    `json:"state"`
	Author    *CRUser       `json:"author,omitempty"`
	Labels    []string      `json:"labels,omitempty"`
	Assignees []string      `json:"assignees,omitempty"`
	Milestone *MilestoneRef `json:"milestone,omitempty"`
	WebURL    string        `json:"web_url,omitempty"`
	CreatedAt time.Time     `json:"created_at"`
	UpdatedAt time.Time     `json:"updated_at"`
	ClosedAt  *time.Time    `json:"closed_at,omitempty"`
	// IsPullRequest 标记这条"issue"其实是 PR。
	//
	// **GitHub 的 issue 列表端点会把 PR 一起返回**(同一条记录既是 issue 也是 PR),
	// 不标记的话消费方没法把两者分开 ⇒ 同一个 PR 既进 issues 快照又进
	// pull_requests 快照,而且**占掉 issue 的数量预算**(默认 500)
	// ⇒ PR 多的仓里真实 issue 可能整批落在预算之外,快照缺项且无任何告警。
	//
	// Gitea/Forgejo 家族的列表端点有 type=issues 过滤(本来就不含 PR),
	// GitLab 的 issues 端点也不含 MR ⇒ 只有 GitHub 需要这个标记。
	IsPullRequest bool `json:"is_pull_request,omitempty"`
}

type IssueComment struct {
	ID        int64     `json:"id"`
	Body      string    `json:"body"`
	Author    *CRUser   `json:"author,omitempty"`
	CreatedAt time.Time `json:"created_at"`
	UpdatedAt time.Time `json:"updated_at"`
}

type IssueLabel struct {
	ID    int64  `json:"id"`
	Name  string `json:"name"`
	Color string `json:"color,omitempty"`
}

type IssueManager interface {
	ListIssues(ctx context.Context, opts ListIssuesOptions) ([]*Issue, int, error)
	GetIssue(ctx context.Context, owner, repo, number string) (*Issue, error)
	CreateIssue(ctx context.Context, opts CreateIssueOptions) (*Issue, error)
	UpdateIssue(ctx context.Context, owner, repo, number string, opts UpdateIssueOptions) (*Issue, error)
	CloseIssue(ctx context.Context, owner, repo, number string) (*Issue, error)
	ReopenIssue(ctx context.Context, owner, repo, number string) (*Issue, error)
	// ListIssueComments returns the issue's comments in full, exhausting
	// the platform's pagination — the result is the complete comment list,
	// not a single page, in the platform's default order.
	ListIssueComments(ctx context.Context, owner, repo, number string) ([]*IssueComment, error)
	CreateIssueComment(ctx context.Context, owner, repo, number, body string) (*IssueComment, error)
	// UpdateIssueComment replaces a comment's body wholesale: every
	// platform's edit surface is a body-only PATCH/PUT with no
	// partial-update semantics, mirroring CreateIssueComment. The platform
	// enforces authorship — only the comment's author (typically the token
	// identity, e.g. a review bot updating its own comment) may edit — so
	// the call fails for anyone else's comment. commentID is the
	// IssueComment.ID from CreateIssueComment or ListIssueComments. number
	// is ignored on platforms whose edit endpoint addresses the comment
	// directly (GitHub, Gitea, Forgejo, GitCode, Gitee); GitLab and Tencent
	// 工蜂 route through the issue, so it must carry that issue's number.
	UpdateIssueComment(ctx context.Context, owner, repo, number string, commentID int64, body string) (*IssueComment, error)
	ListIssueLabels(ctx context.Context, owner, repo string) ([]*IssueLabel, error)
	AddIssueLabels(ctx context.Context, owner, repo, number string, labels []string) error
	RemoveIssueLabel(ctx context.Context, owner, repo, number, name string) error
}

type IssueState string

type JobLog struct {
	Name    string `json:"name"`
	Stage   string `json:"stage"`
	WebURL  string `json:"web_url,omitempty"`
	Trace   string `json:"trace"` // 失败日志尾部（后端截断，量级 ~20KB）
	Truncat bool   `json:"truncated"`
}

type Label struct {
	ID          int64  `json:"id"`
	Name        string `json:"name"`
	Color       string `json:"color,omitempty"`
	Description string `json:"description,omitempty"`
}

type LabelManager interface {
	// ListLabels lists the repository's labels.
	ListLabels(ctx context.Context, owner, repo string, opts ListLabelsOptions) ([]*Label, error)
	// CreateLabel creates a repository label.
	CreateLabel(ctx context.Context, owner, repo string, opts CreateLabelOptions) (*Label, error)
	// UpdateLabel updates the label with the given name. Nil fields in opts
	// are left unchanged.
	UpdateLabel(ctx context.Context, owner, repo, name string, opts UpdateLabelOptions) (*Label, error)
	// DeleteLabel deletes the label with the given name.
	DeleteLabel(ctx context.Context, owner, repo, name string) error
}

type ListCROptions struct {
	Owner string `json:"owner"`
	Repo  string `json:"repo"`
	// State 过滤状态。**空 = 不过滤(全部)**。
	//
	// 各后端的原生词表不同(open/closed/merged 与 opened/closed)⇒ 平台层的
	// "空" 语义必须统一,否则同一个调用在有的平台只拿到 open、在别的平台拿到全部
	// —— 调用方无从察觉 closed/merged 的那部分**静默丢失**。
	// (GitHub / GitLab / 工蜂 本来就是"空=不过滤";Gitee / Gitea / Forgejo /
	//  GitCode 曾把空值映射成 open ⇒ 已对齐。)
	State        CRState `json:"state,omitempty"`
	SourceBranch string  `json:"source_branch,omitempty"`
	TargetBranch string  `json:"target_branch,omitempty"`
	Page         int     `json:"page,omitempty"`
	PerPage      int     `json:"per_page,omitempty"`
}

type ListCommitsOptions struct {
	Page    int    `json:"page,omitempty"`
	PerPage int    `json:"per_page,omitempty"`
	Branch  string `json:"branch,omitempty"`
	Since   string `json:"since,omitempty"` // RFC3339
	Until   string `json:"until,omitempty"` // RFC3339
}

type ListIssuesOptions struct {
	Owner    string     `json:"owner"`
	Repo     string     `json:"repo"`
	State    IssueState `json:"state,omitempty"`
	Assignee string     `json:"assignee,omitempty"`
	Labels   string     `json:"labels,omitempty"`
	Page     int        `json:"page,omitempty"`
	PerPage  int        `json:"per_page,omitempty"`
	// Sort 排序字段("created"|"updated"|"comments"),空 = 平台默认。
	//
	// **增量备份必须用它**:平台默认按 created 倒序 ⇒ "上次备份后被改动的
	// **老** issue"正好被挤在第一页之外,客户端再按 updated 过滤也捞不到
	// (捞到的永远是"最新创建"的那批)。
	//
	// 支持情况(逐后端登记在各自的 divergence 账本里):
	//   - GitHub:支持(sort + direction);
	//   - GitLab:支持(order_by=created_at|updated_at + sort=asc|desc);
	//   - Gitee / Gitea / Forgejo / GitCode / 工蜂:当前 SDK 不暴露(或词表无法确证)
	//     ⇒ 传入被忽略(调用方需自己兜底,见 core 的增量采集)。
	Sort string `json:"sort,omitempty"`
	// Direction 排序方向("asc"|"desc"),空 = 平台默认。
	Direction string `json:"direction,omitempty"`
}

type ListLabelsOptions struct {
	Page    int `json:"page,omitempty"`
	PerPage int `json:"per_page,omitempty"`
}

type ListMilestonesOptions struct {
	State   string `json:"state,omitempty"`
	Page    int    `json:"page,omitempty"`
	PerPage int    `json:"per_page,omitempty"`
}

type ListNotificationsOptions struct {
	All     bool   `json:"all,omitempty"`   // include already-read notifications
	Since   string `json:"since,omitempty"` // RFC3339 timestamp
	Page    int    `json:"page,omitempty"`
	PerPage int    `json:"per_page,omitempty"`
}

type ListRepoOptions struct {
	Owner   string `json:"owner,omitempty"`
	Page    int    `json:"page,omitempty"`
	PerPage int    `json:"per_page,omitempty"`
}

type Logger interface {
	Debug(msg string, keysAndValues ...any)
	Info(msg string, keysAndValues ...any)
	Warn(msg string, keysAndValues ...any)
	Error(msg string, keysAndValues ...any)
}

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

type ManagerOption func(*Manager)

type MarkNotificationsOptions struct {
	LastReadAt string `json:"last_read_at,omitempty"` // RFC3339; empty = mark all
}

type MergeCROptions struct {
	MergeCommitMessage string `json:"merge_commit_message,omitempty"`
	Squash             bool   `json:"squash,omitempty"`
	RemoveSourceBranch bool   `json:"remove_source_branch,omitempty"`
}

type MergeDiff struct {
	Files    []*ChangedFile
	TotalAdd int
	TotalDel int
	RawDiff  string
}

type MigrationInfo struct {
	ID    int64  `json:"id"`
	State string `json:"state"`
	// ArchiveURL 归档下载地址(仅当 state 为 exported 时可用)。
	ArchiveURL string `json:"archive_url"`
}

type MigrationManager interface {
	// CreateMigration 发起迁移导出。org == "" 表示用户级迁移
	// (POST /user/migrations),非空表示组织级(POST /orgs/{org}/migrations)
	// ——同一语义贯穿本接口全部方法。
	CreateMigration(ctx context.Context, org string, opts CreateMigrationOptions) (*MigrationInfo, error)
	// GetMigration 查询迁移状态,org 语义与 CreateMigration 一致。
	GetMigration(ctx context.Context, org string, id int64) (*MigrationInfo, error)
}

type Milestone struct {
	Number      string         `json:"number"`
	Title       string         `json:"title"`
	Description string         `json:"description"`
	State       MilestoneState `json:"state"`
	DueOn       *time.Time     `json:"due_on,omitempty"`
}

type MilestoneManager interface {
	// ListMilestones lists the repository's milestones.
	ListMilestones(ctx context.Context, owner, repo string, opts ListMilestonesOptions) ([]Milestone, error)
	// GetMilestone fetches the milestone with the given number.
	GetMilestone(ctx context.Context, owner, repo, number string) (*Milestone, error)
	// CreateMilestone creates a repository milestone.
	CreateMilestone(ctx context.Context, owner, repo string, opts CreateMilestoneOptions) (*Milestone, error)
	// UpdateMilestone updates the milestone with the given number. Nil
	// fields in opts are left unchanged.
	UpdateMilestone(ctx context.Context, owner, repo, number string, opts UpdateMilestoneOptions) (*Milestone, error)
	// DeleteMilestone deletes the milestone with the given number.
	DeleteMilestone(ctx context.Context, owner, repo, number string) error
}

type MilestoneRef struct {
	Number string `json:"number"`
	Title  string `json:"title,omitempty"`
}

type MilestoneState string

type NormalizedEvent struct {
	ID        string         `json:"id"`
	Type      string         `json:"type"`
	Source    Platform       `json:"source"`
	Timestamp time.Time      `json:"timestamp"`
	Actor     *CRUser        `json:"actor"`
	Repo      *EventRepo     `json:"repo"`
	CR        *ChangeRequest `json:"cr,omitempty"`
	// Issue is set for issue.* events and for comments made on issues;
	// Comment carries the comment body for comment.* events. A comment on
	// a change request populates CR instead of (or alongside) nothing.
	Issue      *Issue          `json:"issue,omitempty"`
	Comment    *IssueComment   `json:"comment,omitempty"`
	Branch     string          `json:"branch,omitempty"`
	Tag        string          `json:"tag,omitempty"`
	CommitSHA  string          `json:"commit_sha,omitempty"`
	Action     string          `json:"action,omitempty"`
	RawPayload json.RawMessage `json:"raw_payload"`
}

type NoteManager interface {
	// UpdateNote rewrites the body of one CR comment.
	UpdateNote(ctx context.Context, owner, repo, number, noteID, body string) (*IssueComment, error)
	// ListNotes returns every comment on the CR, oldest first (all pages).
	ListNotes(ctx context.Context, owner, repo, number string) ([]*IssueComment, error)
}

type Notification struct {
	ID        string              `json:"id"`
	Unread    bool                `json:"unread"`
	Reason    string              `json:"reason"`
	Subject   NotificationSubject `json:"subject"`
	Repo      *EventRepo          `json:"repo,omitempty"`
	UpdatedAt time.Time           `json:"updated_at"`
}

type NotificationManager interface {
	// ListNotifications returns the authenticated user's notifications,
	// exhausting the platform's pagination.
	ListNotifications(ctx context.Context, opts ListNotificationsOptions) ([]*Notification, error)
	// ListRepoNotifications returns notifications for a specific repository.
	ListRepoNotifications(ctx context.Context, owner, repo string, opts ListNotificationsOptions) ([]*Notification, error)
	// MarkNotificationRead marks a single notification thread as read.
	MarkNotificationRead(ctx context.Context, threadID string) error
	// MarkNotificationsRead marks all (or filtered) notifications as read.
	MarkNotificationsRead(ctx context.Context, opts MarkNotificationsOptions) error
	// MarkRepoNotificationsRead marks all notifications for a repository as read.
	MarkRepoNotificationsRead(ctx context.Context, owner, repo string, opts MarkNotificationsOptions) error
}

type NotificationSubject struct {
	Title string `json:"title"`
	Type  string `json:"type"` // "Issue", "PullRequest", "Commit", etc.
	URL   string `json:"url"`
}

type PageFetch[T any] func(ctx context.Context, page int) ([]T, error)

type Platform string

type PlatformBranch struct {
	Name string `json:"name"`
}

type PlatformRepo struct {
	ID            int64    `json:"id"`
	FullName      string   `json:"full_name"`
	Name          string   `json:"name"`
	Owner         string   `json:"owner"`
	Description   string   `json:"description"`
	CloneURL      string   `json:"clone_url"`
	SSHURL        string   `json:"ssh_url"`
	DefaultBranch string   `json:"default_branch"`
	Private       bool     `json:"private"`
	Platform      Platform `json:"platform"`
	// 仓库元数据(用于导入过滤:排除 archived/fork、按 star/语言过滤)
	Archived bool   `json:"archived,omitempty"`
	Fork     bool   `json:"fork,omitempty"`
	Stars    int    `json:"stars,omitempty"`
	Language string `json:"language,omitempty"`
}

type PlatformWebhook struct {
	ID     int64    `json:"id"`
	URL    string   `json:"url"`
	Events []string `json:"events"`
}

type Provider interface {
	// Platform returns the platform type.
	Platform() Platform
	// TestConnection verifies the connection and checks capabilities.
	TestConnection(ctx context.Context) (*TestConnectionResult, error)
	// Capabilities statically declares the optional capability interfaces
	// this provider implements. See CapabilitySet.
	Capabilities() CapabilitySet
	// Divergences statically declares this backend's divergence ledger: the
	// registered places where its behavior departs from the unified
	// semantics (stub / ignore / mapping / detour). Consumers can route on
	// these entries — e.g. provider.Ignores — and docs/divergence-ledger.md
	// is generated from them. Like CapabilitySet this is a compile-time
	// declaration; the contract suite locks ledger entries to behavior.
	Divergences() []Divergence

	RepoManager
	ChangeRequestManager
	WebhookManager
	BranchManager
	DiffManager
	CommitManager
	FileManager
	ReleaseManager
}

type ProviderConstructor func(cfg Config) (Provider, error)

type ProviderError struct {
	Platform   Platform
	Op         string // operation name, e.g., "ListRepos"
	Resource   string // optional resource identifier, e.g., "owner/repo"
	StatusCode int    // 0 when not applicable (e.g. configuration errors)
	// RetryAfter / ResetAt carry the server-advised recovery window when
	// the error is a rate-limit rejection and the platform sent hints
	// (Retry-After header; X-RateLimit-Reset unix seconds). Zero when
	// absent. Copied from the underlying transport error by Wrap; see
	// RateLimitRecovery for the ergonomic accessor.
	RetryAfter time.Duration
	ResetAt    time.Time
	Cause      error // underlying cause; nil when constructed from raw fields
}

type Reaction struct {
	ID    int64   `json:"id"`
	Emoji string  `json:"emoji"`
	User  *CRUser `json:"user,omitempty"`
}

type ReactionManager interface {
	// ListIssueReactions returns all reactions on an issue.
	ListIssueReactions(ctx context.Context, owner, repo, number string) ([]*Reaction, error)
	// AddIssueReaction adds a reaction emoji to an issue. emoji is one of
	// the Reaction* constants (e.g. ReactionHeart).
	AddIssueReaction(ctx context.Context, owner, repo, number, emoji string) (*Reaction, error)
	// RemoveIssueReaction removes a reaction by its platform ID.
	RemoveIssueReaction(ctx context.Context, owner, repo, number string, reactionID int64) error

	// ListIssueCommentReactions returns all reactions on an issue comment.
	ListIssueCommentReactions(ctx context.Context, owner, repo string, commentID int64) ([]*Reaction, error)
	// AddIssueCommentReaction adds a reaction emoji to an issue comment.
	AddIssueCommentReaction(ctx context.Context, owner, repo string, commentID int64, emoji string) (*Reaction, error)
	// RemoveIssueCommentReaction removes a reaction by its platform ID.
	RemoveIssueCommentReaction(ctx context.Context, owner, repo string, commentID int64, reactionID int64) error

	// ListCRReactions returns all reactions on a change request (PR/MR).
	ListCRReactions(ctx context.Context, owner, repo, number string) ([]*Reaction, error)
	// ListCRCommentReactions returns all reactions on a change-request
	// comment (PR review comment / MR note).
	ListCRCommentReactions(ctx context.Context, owner, repo string, commentID int64) ([]*Reaction, error)
	// AddCRCommentReaction adds a reaction emoji to a change-request comment.
	AddCRCommentReaction(ctx context.Context, owner, repo string, commentID int64, emoji string) (*Reaction, error)
	// RemoveCRCommentReaction removes a reaction by its platform ID.
	RemoveCRCommentReaction(ctx context.Context, owner, repo string, commentID int64, reactionID int64) error
}

type ReleaseAsset struct {
	ID                 int64  `json:"id"`
	Name               string `json:"name"`
	Size               int64  `json:"size"`
	ContentType        string `json:"content_type"`
	BrowserDownloadURL string `json:"browser_download_url"`
	URL                string `json:"url"`
}

type ReleaseAssetManager interface {
	// DownloadReleaseAsset 下载 assetID 对应附件并流式写入 w。
	// 非 2xx 响应或无响应体时返回错误。
	DownloadReleaseAsset(ctx context.Context, owner, repo string, assetID int64, w io.Writer) error
}

type ReleaseInfo struct {
	ID          int64     `json:"id"`
	TagName     string    `json:"tag_name"`
	Title       string    `json:"title"`
	Body        string    `json:"body"`
	URL         string    `json:"url"`
	Draft       bool      `json:"draft"`
	Prerelease  bool      `json:"prerelease"`
	CreatedAt   time.Time `json:"created_at"`
	PublishedAt time.Time `json:"published_at"`
	// Assets 发布附件元数据(仅声明 ReleaseAssets 能力的后端填充)。
	Assets []*ReleaseAsset `json:"assets,omitempty"`
}

type ReleaseManager interface {
	ListTags(ctx context.Context, owner, repo string) ([]*TagInfo, error)
	ListReleases(ctx context.Context, owner, repo string) ([]*ReleaseInfo, error)
	CreateRelease(ctx context.Context, owner, repo string, opts CreateReleaseOptions) (*ReleaseInfo, error)
	GetReleaseByTag(ctx context.Context, owner, repo, tag string) (*ReleaseInfo, error)
	UpdateRelease(ctx context.Context, owner, repo, tag string, opts UpdateReleaseOptions) (*ReleaseInfo, error)
	DeleteRelease(ctx context.Context, owner, repo, tag string) error
	GetArchive(ctx context.Context, owner, repo, ref, format string) ([]byte, error)
}

type RepoManager interface {
	ListRepos(ctx context.Context, opts ListRepoOptions) ([]*PlatformRepo, error)
	GetRepo(ctx context.Context, owner, repo string) (*PlatformRepo, error)
	CreateRepo(ctx context.Context, owner string, opts CreateRepoOptions) (*PlatformRepo, error)
	DeleteRepo(ctx context.Context, owner, repo string) error
	UpdateRepo(ctx context.Context, owner, repo string, opts UpdateRepoOptions) (*PlatformRepo, error)
	ForkRepo(ctx context.Context, owner, repo string, opts ForkRepoOptions) (*PlatformRepo, error)
}

type RepoStatsManager interface {
	// ListForks returns all forks of the repository.
	ListForks(ctx context.Context, owner, repo string) ([]*PlatformRepo, error)
	// ListStargazers returns users who have starred the repository.
	ListStargazers(ctx context.Context, owner, repo string) ([]*CRUser, error)
	// ListContributors returns contributors ranked by commit count.
	ListContributors(ctx context.Context, owner, repo string) ([]*Contributor, error)
}

type RequestHook func(ctx context.Context, req *http.Request) context.Context

type ResponseHook func(ctx context.Context, req *http.Request, resp *http.Response, duration time.Duration, err error)

type RetryConfig struct {
	// MaxRetries is the maximum number of retry attempts (not counting the
	// initial request). <= 0 disables retry.
	MaxRetries int
	// BaseDelay is the initial backoff delay before the first retry.
	BaseDelay time.Duration
	// MaxDelay caps the backoff delay. Zero means 30s (the transport
	// default).
	MaxDelay time.Duration
	// RetryOn lists extra HTTP status codes to retry on, in addition to the
	// transport's default set (429 and 5xx).
	RetryOn []int
}

type Review struct {
	ID          int64       `json:"id"`
	User        string      `json:"user"`
	State       ReviewState `json:"state"`
	Body        string      `json:"body"`
	SubmittedAt time.Time   `json:"submitted_at"`
}

type ReviewComment struct {
	Path      string `json:"path"`
	Body      string `json:"body"`
	Line      int    `json:"line,omitempty"`
	StartLine int    `json:"start_line,omitempty"`
	EndLine   int    `json:"end_line,omitempty"`
	Side      string `json:"side,omitempty"`
}

type ReviewCommentResult struct {
	Path       string `json:"path,omitempty"`
	Line       int    `json:"line,omitempty"`
	ExternalID string `json:"external_id,omitempty"`
	Error      string `json:"error,omitempty"`
}

type ReviewManager interface {
	CreateReview(ctx context.Context, owner, repo, number string, opts CreateReviewOptions) (*ReviewResult, error)
	ListReviews(ctx context.Context, owner, repo, number string) ([]Review, error)
	GetReview(ctx context.Context, owner, repo, number string, reviewID int64) (*Review, error)
	RequestReviewers(ctx context.Context, owner, repo, number string, reviewers []string) error
	DismissReview(ctx context.Context, owner, repo, number string, reviewID int64, message string) error
}

type ReviewResult struct {
	ID       string                `json:"id"`
	Body     string                `json:"body,omitempty"`
	HTMLURL  string                `json:"html_url,omitempty"`
	User     *CRUser               `json:"user,omitempty"`
	Comments []ReviewCommentResult `json:"comments,omitempty"`
}

type ReviewState string

type SearchIssueResult struct {
	Number    string     `json:"number"`
	Title     string     `json:"title"`
	Body      string     `json:"body,omitempty"`
	State     IssueState `json:"state"`
	WebURL    string     `json:"web_url,omitempty"`
	Labels    []string   `json:"labels,omitempty"`
	Comments  int        `json:"comments,omitempty"`
	CreatedAt time.Time  `json:"created_at"`
}

type SearchIssuesOptions struct {
	Query   string `json:"q"`
	Repo    string `json:"repo,omitempty"`
	State   string `json:"state,omitempty"`
	Sort    string `json:"sort,omitempty"`
	Order   string `json:"order,omitempty"`
	Page    int    `json:"page,omitempty"`
	PerPage int    `json:"per_page,omitempty"`
}

type SearchManager interface {
	SearchRepos(ctx context.Context, opts SearchReposOptions) ([]*SearchRepoResult, *int, error)
	SearchIssues(ctx context.Context, opts SearchIssuesOptions) ([]*SearchIssueResult, *int, error)
	SearchUsers(ctx context.Context, opts SearchUsersOptions) ([]*SearchUserResult, *int, error)
}

type SearchRepoResult struct {
	FullName      string `json:"full_name"`
	Description   string `json:"description,omitempty"`
	WebURL        string `json:"web_url,omitempty"`
	Stars         int    `json:"stars,omitempty"`
	Forks         int    `json:"forks,omitempty"`
	DefaultBranch string `json:"default_branch,omitempty"`
	Private       bool   `json:"private,omitempty"`
}

type SearchReposOptions struct {
	Query   string `json:"q"`
	Sort    string `json:"sort,omitempty"`
	Order   string `json:"order,omitempty"`
	Page    int    `json:"page,omitempty"`
	PerPage int    `json:"per_page,omitempty"`
}

type SearchUserResult struct {
	Login     string `json:"login"`
	Name      string `json:"name,omitempty"`
	AvatarURL string `json:"avatar_url,omitempty"`
	WebURL    string `json:"web_url,omitempty"`
}

type SearchUsersOptions struct {
	Query   string `json:"q"`
	Sort    string `json:"sort,omitempty"`
	Order   string `json:"order,omitempty"`
	Page    int    `json:"page,omitempty"`
	PerPage int    `json:"per_page,omitempty"`
}

type StarredManager interface {
	// ListStarred 分页列出认证用户 star 的仓库(GET /user/starred)。
	// page/perPage 语义与其他分页方法一致,非法值经 NormalizePageOpts 归一。
	ListStarred(ctx context.Context, page, perPage int) ([]*PlatformRepo, error)
}

type StaticTokenValidator struct {
	Header string
}

type Stats struct {
	Hits      int64
	Misses    int64
	Evictions int64
	Size      int
}

type StatusError struct {
	Status int
	Cause  error
}

type StatusExtractor func(err error) (int, bool)

type TagInfo struct {
	Name   string `json:"name"`
	Commit string `json:"commit"`
}

type TestConnectionResult struct {
	Connected    bool   `json:"connected"`
	Platform     string `json:"platform"`
	UserName     string `json:"user_name"`
	Message      string `json:"message,omitempty"`
	CanListRepos bool   `json:"can_list_repos"`
	CanReadCR    bool   `json:"can_read_cr"`
	CanWriteCR   bool   `json:"can_write_cr"`
	CanWebhook   bool   `json:"can_webhook"`
}

type TokenSource interface {
	Token(ctx context.Context) (string, error)
}

type UpdateBranchProtectionOptions struct {
	RequiredApprovingReviews *int  `json:"required_approving_reviews,omitempty"`
	RequiredStatusChecks     *bool `json:"required_status_checks,omitempty"`
	AllowForcePushes         *bool `json:"allow_force_pushes,omitempty"`
	AllowDeletions           *bool `json:"allow_deletions,omitempty"`
}

type UpdateCROptions struct {
	Title        string `json:"title,omitempty"`
	Description  string `json:"description,omitempty"`
	TargetBranch string `json:"target_branch,omitempty"`
}

type UpdateIssueOptions struct {
	Title     string     `json:"title,omitempty"`
	Body      string     `json:"body,omitempty"`
	State     IssueState `json:"state,omitempty"`
	Assignees []string   `json:"assignees,omitempty"`
	Labels    []string   `json:"labels,omitempty"`
	Milestone string     `json:"milestone,omitempty"` // milestone number/ID as a string; "" = leave unchanged
}

type UpdateLabelOptions struct {
	NewName     *string `json:"new_name,omitempty"`
	Color       *string `json:"color,omitempty"`
	Description *string `json:"description,omitempty"`
}

type UpdateMilestoneOptions struct {
	Title       *string        `json:"title,omitempty"`
	Description *string        `json:"description,omitempty"`
	State       MilestoneState `json:"state,omitempty"`
	DueOn       *time.Time     `json:"due_on,omitempty"`
}

type UpdateReleaseOptions struct {
	Name       *string `json:"name,omitempty"`
	Body       *string `json:"body,omitempty"`
	Draft      *bool   `json:"draft,omitempty"`
	Prerelease *bool   `json:"prerelease,omitempty"`
}

type UpdateRepoOptions struct {
	Name          string `json:"name,omitempty"`
	Description   string `json:"description,omitempty"`
	DefaultBranch string `json:"default_branch,omitempty"`
	Private       *bool  `json:"private,omitempty"`
}

type UpdateWebhookOptions struct {
	URL    *string  `json:"url,omitempty"`
	Secret *string  `json:"secret,omitempty"`
	Events []string `json:"events,omitempty"`
}

type UserManager interface {
	// GetUser returns the user profile for the given username.
	GetUser(ctx context.Context, username string) (*CRUser, error)

	// ResolveUsernames maps a list of usernames to their platform IDs.
	// The returned slice preserves input order; each entry's ID field
	// carries the resolved numeric ID. If a username cannot be resolved,
	// an error is returned for that entry (the partial result up to that
	// point is still valid).
	ResolveUsernames(ctx context.Context, usernames []string) ([]*CRUser, error)
}

type ValidatorFunc struct {
	N  string
	Fn func(r *http.Request, body []byte, secret string) error
}

type WaitOptions struct {
	// Interval is the poll cadence; defaults to DefaultWaitInterval and
	// is clamped up to minWaitInterval.
	Interval time.Duration
	// Timeout bounds the whole wait. Zero uses DefaultWaitTimeout; a
	// negative value disables the budget entirely (rely on your own
	// context deadline). Expiry surfaces as ErrWaitTimedOut carrying the
	// last observed combined state.
	Timeout time.Duration
	// Contexts, when non-empty, restricts the combined state to the
	// named status contexts (e.g. []string{"ci/lint", "ci/test"}).
	// Empty means every context reported on the commit.
	Contexts []string
	// InitialDelay defers the first poll; useful right after
	// CreateCommitStatus, whose result may not be queryable for a
	// moment. Defaults to no delay.
	InitialDelay time.Duration
}

type WebhookConfigManager interface {
	// GetWebhook returns one webhook by its platform ID.
	GetWebhook(ctx context.Context, owner, repo string, webhookID int64) (*PlatformWebhook, error)
	// UpdateWebhook patches one webhook. Nil URL/Secret leave the
	// corresponding setting untouched; a nil Events slice leaves the event
	// set untouched while a non-nil one replaces it wholesale.
	UpdateWebhook(ctx context.Context, owner, repo string, webhookID int64, opts UpdateWebhookOptions) (*PlatformWebhook, error)
}

type WebhookEnvelope struct {
	// Platform selects the registered signature validator.
	Platform Platform
	// EventHeaders are checked in order for the event-type header; the first
	// non-empty value wins (multi-header dialects list fallbacks). Leave
	// empty when the platform dispatches on a payload field (e.g. GitLab's
	// object_kind) instead of a header.
	EventHeaders []string
	// IDPrefix prefixes generated event IDs ("<prefix>-<unixnano>-<key>").
	// Empty falls back to the platform name — the ID is **never empty**
	// (see NewEvent).
	IDPrefix string
	// IDHeaders are checked in order for the platform's **delivery ID**
	// (e.g. GitHub's "X-GitHub-Delivery"); the first non-empty value wins.
	//
	// The delivery ID is a true idempotency key: the platform repeats the
	// same value when it redelivers an event, so callers can deduplicate
	// properly. Without it the ID is synthesized locally and differs on
	// every delivery (no deduplication possible).
	IDHeaders []string
}

type WebhookManager interface {
	CreateWebhook(ctx context.Context, opts CreateWebhookOptions) (*PlatformWebhook, error)
	DeleteWebhook(ctx context.Context, owner, repo string, webhookID int64) error
	ListWebhooks(ctx context.Context, owner, repo string) ([]*PlatformWebhook, error)
	ParseWebhookEvent(r *http.Request, secret string) (*NormalizedEvent, error)
	ValidateWebhookSignature(r *http.Request, secret string) error
}

type WebhookValidator interface {
	Name() string
	Validate(r *http.Request, body []byte, secret string) error
}

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