Client
Server
Reference / @open-music-sdk/core / tAppleMusicClient
Interface: tAppleMusicClient
Defined in: packages/core/src/client.ts:183
The client: what every function of the SDK asks Apple through. createClient makes one; anything with these five methods passes for one wherever a client is taken, since a function checks only the methods it calls.
Methods
as()
ts
as(userToken): tAppleMusicClient;Defined in: packages/core/src/client.ts:257
A client for one listener. Shares the developer token, storefront, store, fetch, limiter, retry policy and hooks.
Parameters
userToken
string | tTokenProvider
The listener's Music User Token, or a function that gives it when a request needs it.
Returns
tAppleMusicClient
A client that sends userToken under /v1/me, made with this client's options otherwise.
Throws
TypeError if userToken is neither a token nor a function.
forUser()
ts
forUser(userId): tAppleMusicClient;Defined in: packages/core/src/client.ts:266
as(), with the token looked up in userTokenStore at each request. A listener the store has no token for is a UserTokenInvalid from the first request that needs it, and that error names the listener as userId does.
Parameters
userId
string
Whose token to look up, under the name the store knows the listener by. It is not checked here.
Returns
tAppleMusicClient
A client that asks the store for the listener's token when a request needs it.
Throws
TypeError if the client was made without a userTokenStore.
paginate()
ts
paginate<T>(from, init?): AsyncIterable<T>;Defined in: packages/core/src/client.ts:237
The items of data across every next page. Breaking out of the loop stops fetching.
from is a path, or a page already fetched: the page's own items come first and nothing is asked for until they run out. With a page, init.params is not sent, since its next link already carries the query. A page is an object with a data list, a next link or both, and anything else handed over is a TypeError, but undefined, which is a last, empty page. A promise of a page is not a page: await it, so that what it rejects with reaches the code that asked.
What a next link answers with has to be a page itself, with data at the top, as a collection's and a relationship's are. A search or a chart answers with its pages nested under results, and is not walked.
A walk has no end but the last page unless init.maxPages gives it one. A next link is followed wherever on Apple's origin it points, so a page or a path from outside your app is as trusted as you make it: for one, pass user: false, so that no Music User Token goes along, and a maxPages.
Nothing runs until the loop first asks: what is thrown is thrown from the loop, not from the call.
Type Parameters
T
T
Parameters
from
string | tPage<T>
The path to ask first, or a page already fetched to begin with.
init?
What each page is asked for with, as request takes it, and maxPages, the most pages to ask for.
Returns
AsyncIterable<T>
The items of data, page by page: those of the page given, then those of each next page asked for.
Throws
TypeError if init.maxPages is given and is not a whole number above 0, from is a promise, or from is neither a path nor a page nor undefined; and as request throws it for a page asked for.
Throws
AppleMusicError as request rejects with for a page; and ApiError when a next link answers with what is no page: not an object, a data that is no list, or a next that is no string.
Throws
The reason init.signal aborted with, when it does.
Throws
Whatever a token provider, store, schema, hook or rate limiter throws, as request does.
request()
ts
request<T>(path, init?): Promise<T>;Defined in: packages/core/src/client.ts:208
One request to Apple: the tokens attached, the parameters encoded, the body read, and the status read as an error where it is one. The developer token goes on every request, and the Music User Token under /v1/me or where init.user says so, so a path has to stay on Apple's origin. A failing attempt is made again as the client's retry policy says, a POST only after a failure that says it was not carried out, and what the last attempt failed with is what the promise rejects with. A 401 gives a developer token provider one chance to replace its token.
Type Parameters
T
T
Parameters
path
string
Where to ask: "v1/...", "/v1/...", or a next link from an answer.
init?
tRequestInit<T>
What to send and what to make of the answer: the method, the query, a JSON body, whether the Music User Token goes along, a schema, a signal and a hook for the response.
Returns
Promise<T>
The parsed body, as init.schema typed it where one was given; undefined when the answer had no body.
Throws
TypeError if path leaves https://api.music.apple.com or is no URL, a value of init.params or init.body cannot be encoded, a GET is given a body, init.signal is no AbortSignal, or a token provider gives what is no token.
Throws
AppleMusicError, once the retries are over, with _tag DeveloperTokenInvalid when Apple answers 401; UserTokenInvalid when Apple answers 403, or the path needs a Music User Token and the client has none; RateLimited when Apple answers 429; ApiError on any other failing status, or a 2xx body that is not JSON; ValidationError when init.schema finds issues; NetworkError when fetch fails, Apple answers with a redirect, which is not followed, or the body cannot be read while init.signal has not fired. A DeveloperTokenUnavailable is never made here: it is a token provider's, passed on.
Throws
The reason init.signal aborted with, when it does.
Throws
Whatever a token provider, a user token store, a schema's validate, an onRequest or onResponse hook or the rate limiter throws, as it is.
storefront()
ts
storefront(): Promise<string>;Defined in: packages/core/src/client.ts:249
The configured storefront, or the listener's, resolved once. A failure is not kept: the next call asks again.
Returns
Promise<string>
The storefront's id, such as "us": the one the client was created with, or else the one /v1/me/storefront names for the listener, asked for once and kept.
Throws
TypeError if a token provider gives what is no token, as request throws it.
Throws
AppleMusicError with _tag UserTokenInvalid when no storefront was configured and there is no Music User Token to look one up with; otherwise what request rejects with for v1/me/storefront, and ApiError when its answer names no storefront.
Throws
Whatever a token provider, store, hook or rate limiter throws, as request does.