@kody/gitlab

export type GitlabAuthMode = 'oauth' | 'pat'

export type GitlabQueryValue = string | number | boolean | null | undefined

export type GitlabQuery = Record<string, GitlabQueryValue>

export type GitlabHeaders = Record<string, string>

export interface GitlabAuthInput {
	/**
	 * Saved OAuth integration name. Defaults to `gitlab` when `secretName` is
	 * omitted. Pass a distinct name (`gitlab-work`, `gitlab-bot`, …) for each
	 * additional connected GitLab identity.
	 */
	integrationName?: string
	/**
	 * Personal access token secret name. When set, the PAT lane is used and
	 * `integrationName` is ignored. The documented default PAT name is
	 * `gitlabAccessToken`.
	 */
	secretName?: string
	/**
	 * Alias for `integrationName`.
	 */
	account?: string
	/**
	 * REST API base, including `/api/v4`. Defaults to `https://gitlab.com/api/v4`.
	 * Use this for self-hosted GitLab.
	 */
	apiBaseUrl?: string
	/**
	 * GitLab instance origin such as `https://gitlab.example.com`. Used to derive
	 * `apiBaseUrl` when that field is omitted.
	 */
	instanceUrl?: string
}

export interface GitlabResolvedAuth {
	mode: GitlabAuthMode
	integrationName: string | null
	secretName: string | null
	label: string
	apiBaseUrl: string
	apiHost: string
}

export interface GitlabAuthLaneInfo {
	lane: GitlabAuthMode
	default: boolean
	integrationName?: string
	secretName?: string
	connectUrl?: string
	secretSetupUrl?: string
	useWhen: string
	avoidWhen: string
	mutationGuidance: string
}

export interface GitlabRequestOptions extends GitlabAuthInput {
	path: string
	method?: string
	query?: GitlabQuery
	headers?: GitlabHeaders
	body?: unknown
	throwOnError?: boolean
	/**
	 * When true, mutating requests return a preview and do not call GitLab.
	 * Safe methods (`GET`, `HEAD`, `OPTIONS`) still execute so smoke tests work.
	 */
	dryRun?: boolean
	/**
	 * Required for live mutating REST calls (`POST`, `PUT`, `PATCH`, `DELETE`).
	 * Omit when `dryRun` is true.
	 */
	confirm?: boolean
}

export interface GitlabResponse<TData = unknown> {
	auth: GitlabResolvedAuth
	url: string
	ok: boolean
	status: number
	statusText: string
	headers: GitlabHeaders
	data: TData | null
	text: string
	dryRun?: boolean
}

export interface GitlabPaginateOptions
	extends Omit<GitlabRequestOptions, 'body' | 'throwOnError' | 'dryRun' | 'confirm'> {
	maxPages?: number
}

export interface GitlabPaginationResult<TItem = unknown> {
	auth: GitlabResolvedAuth
	items: TItem[]
	pages: number
	lastResponse: GitlabResponse<unknown> | null
}

export interface GitlabCurrentUser {
	auth: GitlabResolvedAuth
	id: number
	username: string
	name: string
	webUrl: string
	state: string
}

export interface GitlabProjectLocator {
	projectId: string
	projectPath: string
}

export interface GitlabIssueLocator extends GitlabProjectLocator {
	issueIid: number
}

export interface GitlabMergeRequestLocator extends GitlabProjectLocator {
	mergeRequestIid: number
}

export interface GitlabPipelineLocator extends GitlabProjectLocator {
	pipelineId: number
}

/**
 * Describes the shared type exports for the GitLab package.
 */
export default function describeGitlabTypes() {
	return {
		auth: 'integrationName (OAuth, default gitlab) or secretName (PAT); optional apiBaseUrl / instanceUrl',
		request: 'GitlabRequestOptions -> GitlabResponse<TData>',
		paginate: 'GitlabPaginateOptions -> GitlabPaginationResult<TItem>',
	}
}