@kentcdodds/spotify

@kentcdodds/spotify — agent notes

Human setup and intent live in README.md. This file is for agents: imports, smoke snippets, and edge cases. Integration ids by name only — never paste token values. Do not disable live webhooks or jobs.

Auth / accounts

Every export accepts optional account: 'personal' | 'family' (or the integration name). Reconnect: /connect/oauth?provider=spotify / ...?provider=spotify-family.

Hosted app: https://kentcdodds.kody.run/packages/spotify.

Import paths

Prefer static kody:@kentcdodds/spotify/... imports from execute.

Smoke / read checks

No dedicated smoke-test export. Prefer read-only calls:

import accounts from 'kody:@kentcdodds/spotify/accounts'
import playbackState from 'kody:@kentcdodds/spotify/playback-state'
import getDevices from 'kody:@kentcdodds/spotify/get-devices'

export default async function main() {
	const catalog = accounts()
	const state = await playbackState({ account: 'personal' })
	const devices = await getDevices({ account: 'personal' })
	return { catalog, state, deviceNames: devices.map((d) => d.name) }
}

import search from 'kody:@kentcdodds/spotify/search'

export default async function main() {
	return await search({ query: 'radiohead', types: ['track'], limit: 5 })
}

Playback / device targeting

Prefer deviceName (and optional deviceType) over opaque deviceId:

import getDevices from 'kody:@kentcdodds/spotify/get-devices'
import playContext from 'kody:@kentcdodds/spotify/play-context'
import transferPlayback from 'kody:@kentcdodds/spotify/transfer-playback'

export default async function main() {
	const devices = await getDevices()
	await transferPlayback({ deviceName: devices[0]?.name, play: true })
	return await playContext({
		contextUri: 'spotify:playlist:37i9dQZF1DX0XUsuxWHRQd',
		deviceName: 'Living Room',
	})
}

import createPlaylist from 'kody:@kentcdodds/spotify/create-playlist'

export default async function main() {
	return await createPlaylist({ account: 'family', name: 'Road Trip', public: false })
}

Mutating helpers (play, queue, playlist edits, library saves, transfer) have no package-level dryRun / confirm — get explicit user approval before changing playback or library state. Prefer read checks first.

Edge cases

• Family account: fallbackDeviceId and defaultCollectionUri are null — require an active device or explicit deviceName / deviceId.
• Personal account may fall back to a configured default device/collection when nothing is playing.
• search: prefer types (array); type is accepted as an alias.
• skip: direction is 'next' (default) or 'previous'.
• set-volume: volumePercent 0–100.
• Never paste Spotify device ids into chat or across safety-sensitive tool boundaries — pass deviceName instead.
• Do not disable the hosted package app or any related jobs/webhooks.