@kody/spotify

import type { SpotifyIntegrationInput } from './accounts.ts'

/** Optional Spotify integration name on export params (default `spotify`). */
export type WithIntegration = SpotifyIntegrationInput

export type WithDryRun = {
	/** When true, validate and return a preview without calling a Spotify write. */
	dryRun?: boolean
}

export type DeviceParams = WithIntegration & {
	/**
	 * Preferred device selector for agents: match a Connect device by name
	 * (case-insensitive substring). Resolved inside the package so opaque
	 * Spotify device ids never need to cross the agent tool boundary.
	 */
	deviceName?: string
	device_name?: string
	/** Optional Connect device type filter (e.g. "Speaker", "Computer"). */
	deviceType?: string
	device_type?: string
	/**
	 * Advanced escape hatch: raw Spotify Connect device id. Prefer
	 * `deviceName` / `deviceType`. Omit all selectors to use the active device.
	 */
	deviceId?: string
	device_id?: string
}

export type MutationDeviceParams = DeviceParams & WithDryRun

export type PlayPauseParams = MutationDeviceParams

export type SeekParams = MutationDeviceParams & {
	positionMs?: number
	position_ms?: number
}

export type PlaybackStateParams = WithIntegration

export type GetQueueParams = WithIntegration

export type GetDevicesParams = WithIntegration

export type GetProfileParams = WithIntegration

export type SkipParams = MutationDeviceParams & {
	direction?: 'next' | 'previous'
}

export type TransferPlaybackParams = MutationDeviceParams & {
	play?: boolean
}

export type SetVolumeParams = MutationDeviceParams & {
	volumePercent?: number
	volume?: number
}

export type SetRepeatParams = MutationDeviceParams & {
	state: 'track' | 'context' | 'off'
}

export type SetShuffleParams = MutationDeviceParams & {
	state: boolean
}

export type PlayContextParams = MutationDeviceParams & {
	contextUri?: string
	context_uri?: string
	shuffled?: boolean
	offsetIndex?: number
}

export type AddToQueueParams = MutationDeviceParams & {
	uri?: string
	spotifyUri?: string
}

export type CreatePlaylistParams = WithIntegration &
	WithDryRun & {
		name: string
		description?: string
		public?: boolean
	}

export type PlaylistIdParams = WithIntegration & {
	playlistId?: string
	playlist_id?: string
}

export type PlaylistTracksParams = PlaylistIdParams &
	WithDryRun & {
		uris: string[]
	}

export type FollowPlaylistParams = PlaylistIdParams & WithDryRun

export type ListPlaylistsParams = WithIntegration & {
	limit?: number
}

export type SaveTracksParams = WithIntegration &
	WithDryRun & {
		uris?: string[]
		ids?: string[]
	}

export type GetRecentlyPlayedParams = WithIntegration & {
	limit?: number
}

export type GetSavedTracksParams = WithIntegration & {
	limit?: number
}

export type GetRecommendationsParams = WithIntegration & {
	seedTracks?: string[]
	seedArtists?: string[]
	seedGenres?: string[]
	limit?: number
	targetEnergy?: number
	targetValence?: number
}

export type GetTopItemsParams = WithIntegration & {
	type: 'tracks' | 'artists'
	timeRange?: 'short_term' | 'medium_term' | 'long_term'
	time_range?: string
	limit?: number
}

export type GetTrackParams = WithIntegration & {
	ids: string[]
}

export type SearchParams = WithIntegration & {
	query?: string
	q?: string
	types?: Array<'track' | 'album' | 'artist' | 'playlist'>
	/** Alias of `types`. A single value or array; same allowed kinds. */
	type?:
		| 'track'
		| 'album'
		| 'artist'
		| 'playlist'
		| Array<'track' | 'album' | 'artist' | 'playlist'>
	limit?: number
}