Spotify
@jamesakeech/spotifyv2026.07.07.1
01README
Monitor a single user's Spotify listening activity via the Spotify Web API — recently-played tracks (accumulate over time), plus top-artists and top-tracks rankings — with built-in OAuth helpers to obtain the refresh token.
02Models
@jamesakeech/spotifyv2026.07.07.1spotify.ts
Global Arguments
| Argument | Type | Description |
|---|---|---|
| clientId | string | Spotify app Client ID (developer.spotify.com → your app → Settings). |
| clientSecret | string | Spotify app Client Secret. Source from a vault. |
| refreshToken | string | OAuth refresh token obtained via the `authorize` method. Required for the |
| redirectUri | string | Redirect URI registered in the Spotify app settings. Must match exactly |
fn authorize_url()
Build the one-time Spotify OAuth authorization URL. Open it in a
fn authorize(code: string)
Exchange an authorization `code` (from the redirect after
| Argument | Type | Description |
|---|---|---|
| code | string | The `code` query parameter from the redirect URL |
fn recent_plays(limit: number, after?: number)
Pull the current user's recently-played tracks (Spotify returns only
| Argument | Type | Description |
|---|---|---|
| limit | number | Max plays to fetch (Spotify caps this endpoint at 50) |
| after? | number | Only return plays strictly after this Unix-millisecond timestamp |
fn top_artists(timeRange: enum, limit: number)
Pull the user's top artists for a time range (short_term ~4wk,
| Argument | Type | Description |
|---|---|---|
| timeRange | enum | short_term (~4 weeks), medium_term (~6 months), long_term (~1 year) |
| limit | number | Max artists to fetch (Spotify caps this at 50) |
fn top_tracks(timeRange: enum, limit: number)
Pull the user's top tracks for a time range (short_term ~4wk,
| Argument | Type | Description |
|---|---|---|
| timeRange | enum | short_term (~4 weeks), medium_term (~6 months), long_term (~1 year) |
| limit | number | Max tracks to fetch (Spotify caps this at 50) |
Resources
authUrl(1d)— The one-time OAuth authorization URL to open in a browser
credential(infinite)— The OAuth refresh token produced by `authorize` (secret)
play(infinite)— A recently-played track (one record per play; accumulate over time)
topArtist(infinite)— A top artist for a time range (one record per artist)
topTrack(infinite)— A top track for a time range (one record per track)
03Stats
A
100 / 100
Downloads
0
Archive size
12.7 KB
- Has README or module doc2/2earned
- README has a code example1/1earned
- README is substantive1/1earned
- Most symbols documented1/1earned
- No slow types (deprecated)1/1earned
- Dependencies pass trust audit2/2earned
- Has description1/1earned
- Platform support declared (or universal)2/2earned
- License declared1/1earned
- Verified public repository2/2earned
04Platforms
05Labels