Reference / @open-music-sdk/browser / tBrowserMusic

Interface: tBrowserMusic

Defined in: integrations/browser/src/client.ts:44

The page's client: tMusic with the developer-token provider on it, which createConnect takes, and kept through as() and forUser(). It is frozen and inherits nothing, and each of its functions can be handed on by itself.

Extends

• Omit<tMusic, "as" | "forUser">

Properties

catalog

readonly catalog: tEndpointNamespace<tCatalogFunctions>;

Defined in: integrations/browser/src/client.ts:48

The catalog's functions, bound to this client: catalog(client) of @open-music-sdk/client-catalog.

Overrides

Omit.catalog

---

developerToken

readonly developerToken: tDeveloperTokenProvider;

Defined in: integrations/browser/src/client.ts:46

The provider that fetches the token from tokenUrl: what Apple's script is configured with, by createConnect.

---

playlists

readonly playlists: tPlaylists;

Defined in: integrations/browser/src/client.ts:52

The playlist verbs, bound to this client: playlists(client) of @open-music-sdk/lib-playlists.

Overrides

Omit.playlists

---

user

readonly user: tEndpointNamespace<tUserFunctions>;

Defined in: integrations/browser/src/client.ts:50

The listener's library and its functions, bound to this client: user(client) of @open-music-sdk/client-user.

Overrides

Omit.user

Methods

as()

as(userToken): tBrowserMusic;

Defined in: integrations/browser/src/client.ts:62

A client for one listener: the same developer token, limiter, retry policy and hooks, with the namespaces made for it and the provider kept on it.

Parameters

userToken

string | tTokenProvider

The listener's Music User Token, or a provider that gives it.

Returns

tBrowserMusic

The listener's client, frozen.

Throws

TypeError if userToken is neither a token nor a function. The three namespaces are fixed here, and each checks nothing but the client it is handed, which is one just made, so this is the whole list.

---

forUser()

forUser(userId): tBrowserMusic;

Defined in: integrations/browser/src/client.ts:72

as(), with the token looked up in the client's userTokenStore at each request; a listener the store has no token for is a UserTokenInvalid at the first request.

Parameters

userId

string

The id the store keeps the listener's token under.

Returns

tBrowserMusic

The listener's client, frozen.

Throws

TypeError if the client was made without a userTokenStore. The three namespaces are fixed here, and each checks nothing but the client it is handed, which is one just made, so this is the whole list.

---

paginate()

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?

tPaginateInit<T>

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.

Inherited from

Omit.paginate

---

request()

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.

Inherited from

Omit.request

---

storefront()

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.

Inherited from

Omit.storefront