Open Music SDK
Client
Server

Appearance

Reference / @open-music-sdk/core

@open-music-sdk/core ​

You probably don't want this package. Most apps install one integration and import everything from it: see Which package to install in the repository's README.

The HTTP client every other package is built on. It sends each request to the Apple Music API with your tokens, follows next links, turns Apple's status codes into errors, and retries what is worth retrying. It depends on nothing outside the family, and runs anywhere fetch does.

Most apps install server, browser or react instead, which build their client with this package. Use core to build your own client, or to call a path no function covers.

Installation ​

pnpm add @open-music-sdk/core
pnpm add -D @open-music-sdk/types

The second line is for the types the example imports.

Documentation ​

Example ​

Anywhere fetch runs. developerToken, musicUserToken and askListenerToSignInAgain stand for your own code:

ts
import { createClient, isAppleMusicError } from "@open-music-sdk/core";
import type { tSongsResponse } from "@open-music-sdk/types";

const music = createClient({ developerToken, storefront: "us" }); // a token, or a provider from developer-token

const { data } = await music.request<tSongsResponse>("v1/catalog/us/songs", { params: { ids: ["1613600188"] } });

const listener = music.as(musicUserToken); // the same client, for one listener
try {
  for await (const playlist of listener.paginate("v1/me/library/playlists")) console.log(playlist);
} catch (e) {
  if (isAppleMusicError(e, "UserTokenInvalid")) askListenerToSignInAgain();
  else throw e;
}

What's in it ​

ExportWhat it does
createClient(options)The client, with request, paginate, storefront, as and forUser. Its options are checked when you create it.
withNamespaces(client, namespaces)The client with namespaces such as catalog on it, made again for each client as() and forUser() give. An integration's client is made this way.
AppleMusicError, isAppleMusicError(e, tag?)The one class for every runtime failure, and the guard that narrows to it, or to one _tag
retry(fn, policy?, signal?), retryableBackoff with full jitter that honours Retry-After, and the default test of what is worth another attempt
createRateLimiter(options)A token bucket to share between every client on one developer token
parseRetryAfter(header), sleep(ms, signal?)A Retry-After header in milliseconds, and a wait that an abort ends
parseToken(value)The one rule for what a token is: the value trimmed, or undefined
readBounded(message, maxBytes)A body read as text up to a limit, with the rest cancelled
got(value)What a value is, for an error that must not show it
hostsOf(fn, value, example), isOnHost(url, hosts)A caller's list of allowed hosts, and whether a URL is https on one of them
The typestClientOptions, tRequestInit, tPaginateInit, tAppleMusicClient, tTokenProvider, tUserTokenStore, tRetryPolicy, tRateLimiter and the rest

These are for a package that names endpoints, as the clients do. An app has no need of them:

ExportWhat it does
endpoint, resourceGetter, resourcesGetter, resourcesFinder, resourceLister, relationshipGetterDeclare a function for one endpoint, which you call with a client or bind to one
endpointNamespace(fn, client, endpoints)Every such function, bound to one client
initOf, walkOf, inStorefront, signalOfThe options every such function takes, turned into what request takes
segmentOf, listOf, textOf, typedIdsOf, optionsOf, clientOfThe checks on what a function is handed. A mistake is a TypeError that names the function and the argument.
has, isName, isPlain, itemsOf, ownOfWhat those checks are made of, for a package with a check of its own to make

Call an endpoint the clients don't cover shows how to declare one, and each builder's reference says what it checks.

Classes ​

Interfaces ​

Type Aliases ​

Functions ​

MIT licensed. Not affiliated with, endorsed by, or sponsored by Apple Inc. Apple Music and MusicKit are trademarks of Apple Inc.