export type ZoomAuthMode = 'oauth' | 's2s'

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

export type ZoomQuery = Record<string, ZoomQueryValue>

export type ZoomHeaders = Record<string, string>

export interface ZoomAuthInput {
	/**
	 * Saved OAuth integration name. Defaults to `zoom` when the S2S lane is
	 * not selected. Pass a distinct name (`zoom-work`, …) for each extra
	 * connected Zoom identity.
	 */
	integrationName?: string
	/**
	 * Alias for multi-account selection. `work` becomes `zoom-work` (OAuth)
	 * or `zoomClientId-work` / `zoomS2sClientSecret-work` (S2S). A value that
	 * already starts with `zoom-` is used as-is.
	 */
	account?: string
	/**
	 * Force `oauth` or `s2s`. When omitted, S2S is used if `accountId` or any
	 * S2S secret override is present; otherwise OAuth.
	 */
	auth?: ZoomAuthMode
	/**
	 * Server-to-Server Zoom account ID (plain value from the app's App
	 * Credentials page; not a secret). Required for every S2S call because
	 * Zoom's token exchange only accepts it in the query or body, where Kody
	 * never substitutes secrets.
	 */
	accountId?: string
	/**
	 * Server-to-Server client ID secret name. Documented default:
	 * `zoomClientId`.
	 */
	clientIdSecret?: string
	/**
	 * Server-to-Server client secret name. Documented default:
	 * `zoomS2sClientSecret`. Distinct from the OAuth app `zoomClientSecret`
	 * stored by `/connect/oauth`.
	 */
	clientSecretSecret?: string
}

export interface ZoomResolvedAuth {
	mode: ZoomAuthMode
	integrationName: string | null
	accountId: string | null
	clientIdSecret: string | null
	clientSecretSecret: string | null
	label: string
	apiBaseUrl: string
	apiHost: string
}

export interface ZoomAuthLaneInfo {
	lane: ZoomAuthMode
	default: boolean
	integrationName?: string
	clientIdSecret?: string
	clientSecretSecret?: string
	connectUrl?: string
	clientIdSetupUrl?: string
	clientSecretSetupUrl?: string
	useWhen: string
	avoidWhen: string
	mutationGuidance: string
}

export interface ZoomRequestOptions extends ZoomAuthInput {
	path: string
	method?: string
	query?: ZoomQuery
	headers?: ZoomHeaders
	body?: unknown
	throwOnError?: boolean
	/**
	 * When true, mutating requests return a preview and do not call Zoom.
	 * 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 ZoomResponse<TData = unknown> {
	auth: ZoomResolvedAuth
	url: string
	ok: boolean
	status: number
	statusText: string
	headers: ZoomHeaders
	data: TData | null
	text: string
	dryRun?: boolean
}

export interface ZoomPaginateOptions
	extends Omit<ZoomRequestOptions, 'body' | 'throwOnError' | 'dryRun' | 'confirm'> {
	maxPages?: number
	/** JSON array field that holds the page items (`meetings`, `users`, …). */
	itemsKey?: string
}

export interface ZoomPaginationResult<TItem = unknown> {
	auth: ZoomResolvedAuth
	items: TItem[]
	pages: number
	nextPageToken: string | null
	lastResponse: ZoomResponse<unknown> | null
}

export interface ZoomCurrentUser {
	auth: ZoomResolvedAuth
	id: string | null
	email: string | null
	displayName: string | null
	firstName: string | null
	lastName: string | null
	type: number | null
	status: string | null
	timezone: string | null
}

export interface ZoomUserLocator {
	userId: string
}

export interface ZoomMeetingLocator {
	meetingId: string
	occurrenceId?: string
}

export interface ZoomWebinarLocator {
	webinarId: string
	occurrenceId?: string
}

/**
 * Describes the shared type exports for the Zoom package.
 */
export default function describeZoomTypes() {
	return {
		auth: 'integrationName (OAuth, default zoom) or S2S (accountId param plus secrets zoomClientId / zoomS2sClientSecret); account selects zoom-*',
		request: 'ZoomRequestOptions -> ZoomResponse<TData>',
		paginate: 'ZoomPaginateOptions -> ZoomPaginationResult<TItem>',
	}
}