connector-spotify

Spotify with spotify-client

Motoko bindings for the
Spotify Web API,
generated from Spotify's official OpenAPI spec: 15 API modules, 270
operations. The package is built in icp-cli mode (mo:ic/Types for the
management-canister interface), so it pulls ic as a dependency and pins
PocketIC in [toolchain].

Backend

Reading catalog data and driving the player. The token always comes from the
caller — the canister never holds a Spotify client secret:

import { getTrack } "mo:spotify-client/Apis/TracksApi";
import { getInformationAboutTheUsersCurrentPlayback; skipUsersPlaybackToNextTrack } "mo:spotify-client/Apis/PlayerApi";
import { type Config; defaultConfig } "mo:spotify-client/Config";

persistent actor {
  func config(accessToken : Text) : Config = { defaultConfig with auth = ?#bearer accessToken };

  // Catalog read — a client-credentials token suffices. `market = ""` omits the
  // parameter; empty strings and zeroes are how optional query params are
  // dropped, there is no `?Text` to leave null.
  public func trackName(accessToken : Text, id : Text) : async ?Text {
    let track = await* getTrack(config accessToken, id, "");
    track.name;
  };

  // User read — needs a user token with `user-read-playback-state`. An idle
  // player answers 204 with an empty body, which the generated decoder cannot
  // parse, so it rejects; treat that as "nothing playing", not as an error.
  public func nowPlaying(accessToken : Text) : async ?Bool {
    try {
      let state = await* getInformationAboutTheUsersCurrentPlayback(config accessToken, "", "");
      state.is_playing;
    } catch (_err) {
      null;
    };
  };

  // User write — needs `user-modify-playback-state`. Returns `()`, and since
  // 0.3.0 a non-2xx status rejects, so a missing scope or an expired token
  // surfaces here instead of looking like success.
  public func skip(accessToken : Text) : async () {
    await* skipUsersPlaybackToNextTrack(config accessToken, "");
  };
}

Auth: the canister never sees a client secret

Every call needs an OAuth 2.0 bearer access token, minted off-chain and
passed in. Two flows matter:

1. Client Credentials — server-to-server, no user. Reads public catalog
   only: search, getTrack, getAnAlbum, getAnArtist, getNewReleases,
   getCategories, getAvailableMarkets, public playlists, public shows. It
   cannot touch any /me/* endpoint, the library, or the player.
2. Authorization Code with PKCE — user-facing. Required for every /me/*
   call, playlist mutation, library write and player command, each gated by its
   own scope (user-read-playback-state, user-modify-playback-state,
   playlist-modify-public, user-library-read, …). Scopes absent from the
   token surface as 403, not as a validation error.

Tokens expire after one hour and refresh is off-chain too. Treat a 401 as
"ask the client to refresh and retry", never as a permanent failure, and never
store a client secret in the canister.

Calls are non-replicated by default

The package ships is_replicated = ?false in defaultConfig, and 91 of the
135 operations depend on it. The generator already pins non-replication per
request for the 27 PUT and 17 DELETE operations, because the IC requires it
there — so playlist edits and library saves were never at risk. The default is
what covers the rest:

• the 7 POSTs, which include addToQueue and both skip endpoints. These
  are not idempotent, so replicated they would queue a track ~13 times and skip
  ~13 tracks;
• all 84 GETs, which are non-deterministic for the player —
  currently-playing carries timestamp and progress_ms, differing per node —
  and would cost ~13x the cycles even where they agree.

You don't set the flag yourself; the default is correct. Override with
is_replicated = ?true only together with a transform that strips the
volatile fields.

Upgrading from 0.2.x — the old advice was backwards. That skill told callers
to keep is_replicated = null for mutations "because consensus matters", and
showed let userCfg = { cfg with is_replicated = null }. Carrying that forward
is now actively harmful: null means replicated, so every addToQueue and
skip would fire once per replica. Delete any such override and take
defaultConfig as it comes.

Everything in a response is optional

Spotify marks almost no response field required, so the models are all-optional:
TrackObject.name : ?Text, .artists : ?[SimplifiedArtistObject],
CurrentlyPlayingContextObject.is_playing : ?Bool. Reach through with a do ?
block rather than nested switches, and decide what absence means for your
caller — Spotify omits fields your token's scopes don't cover.

IDs, not URIs

Endpoint parameters take Spotify's base-62 IDs
(11dFghVXANMlKmJXsNCbNl), not URIs (spotify:track:11dFghVXANMlKmJXsNCbNl)
and not URLs. When a user pastes a Spotify link, extract the segment after the
last / and before any ?. The uris parameters on playlist operations are
the exception — those do take full spotify:track:… URIs.

Starting playback

PlayerApi.startAUsersPlayback takes the four fields as scalars —
context_uri : ?Text, uris : ?[Text], position_ms : ?Int — and
transferAUsersPlayback takes play : ?Bool. Pick one of uris (explicit
tracks) or context_uri (an album, artist or playlist), never both.

offset is the exception: it is a free-form object in the spec, so the
generator maps it to ?Map<Text, Text> and serialises every value as a
string. {"uri": "spotify:track:…"} therefore works, while Spotify's other
documented form {"position": 5} goes out as {"position": "5"} and is
rejected. Offset into a context by URI, not by index.

One operation does not work

PlaylistsApi.uploadCustomPlaylistCover — the spec declares the body as
image/jpeg (format: byte), but the generator only ever emits JSON request
bodies, so the call sends Content-Type: application/json with the base64
wrapped in JSON quotes. Spotify rejects it. This is not new in 0.3.0: 0.2.2
JSON-wrapped the raw Blob instead, equally wrong on the wire. Do not offer
custom playlist cover upload, and do not hand-roll it with ic.http_request;
raise it on
caffeinelabs/skills-internal.

Everything else in the surface is sound — unlike some connectors, there are no
stubbed oneOf converters, no operation silently dropping its request body, and
no endpoint returning a non-JSON body through the JSON decoder.

The idle player rejects instead of returning "nothing playing"

PlayerApi.getInformationAboutTheUsersCurrentPlayback and
getTheUsersCurrentlyPlayingTrack answer 204 with an empty body when
playback is not active. The generated code treats every 2xx as the 200 schema
and runs the JSON decoder over it, so an idle player produces
Error.reject(… Failed to parse JSON …) rather than an absent value. Wrap both
in try/catch and read a rejection as "nothing playing", as the §Backend
sample does.

This is a codegen gap, not a Spotify quirk: the spec declares
'204': Playback not available or active for the first operation (the generator
ignores no-content 2xx responses and has no ?T return shape for them), while
for the second Spotify returns 204 in practice without declaring it at all.
Modelling declared no-content responses would change the generated signature to
?CurrentlyPlayingContextObject, so it belongs in the plugin as its own
change.

Every write now reports its status

Until 0.3.0 the 43 operations returning async* () — skip, pause,
addToQueue, every library and playlist mutation — discarded the HTTP response
entirely, so a 401, 403 or 429 was indistinguishable from success. They now
reject on any non-2xx status. Expect try/catch around writes to actually
fire: a missing scope surfaces as 403 where it previously looked like a
successful no-op.

Cycles and response sizes

defaultConfig.cycles = 30_000_000_000 suits a typical single-object read.
Large pages need more: search with limit=50, getAnAlbum on a long
tracklist, or getAudioAnalysis (which returns a very large object) want
cycles = 100_000_000_000 and an explicit
max_response_bytes = ?2_000_000.

Errors

Non-2xx responses and decode failures throw Error.reject(…). The client is
generated with diagnostics, so the message is
HTTP <status> body[<n>B]=<first 100 chars>: <reason> — enough to separate a
401 (expired token) from a 403 (missing scope) from a 404 (bad ID) without extra
logging. Catch with try/catch and surface Error.message(err).