Reference / @open-music-sdk/developer-token / developerTokenFetcher

Function: developerTokenFetcher()

function developerTokenFetcher(url, options?): tDeveloperTokenProvider;

Defined in: fetcher.ts:82

A developerToken provider that fetches the token from an endpoint you host, for code that must not hold the private key. The endpoint answers 2xx with the JWT as text, or as JSON { "token": "<jwt>" }.

The token is reused and replaced in the background halfway through the life it had left, concurrent requests share one fetch, and a token Apple answers 401 to is fetched again. Whatever goes wrong at the endpoint is DeveloperTokenUnavailable, carrying the endpoint's status when it answered, so it is never mistaken for an answer from Apple.

The request is a plain GET with cache: "no-store". A redirect is refused, so the token comes from url or not at all: give the final URL, not one your framework redirects, such as /api/token to /api/token/. The answer is read up to 16 KB, counted after any decompression, and a token longer than 8 KB is not believed. What goes wrong is retried by the client's policy as this says:

The endpoint	status	Retried by the client
is unreachable, times out, or drops the connection mid-body	none	Yes
redirects, as Node and Workers hand a redirect over	the redirect's 3xx	No
redirects, as a browser hands one over, with no status	none	Yes
answers 429, or a 5xx other than 501	the endpoint's	Yes, after its Retry-After if it sent one
answers any other status that is not 2xx	the endpoint's	No
answers 2xx without a JWT that has an exp, or with more than 16 KB	the endpoint's	No

Parameters

url

string | URL

The endpoint: http or https, with no username or password in it. Absolute, or relative to the document's base URL in a browser, resolved again each time a token is fetched, so a <base> element added to the page later changes where the token is fetched from.

options?

tFetcherOptions = {}

The fetch to use, how far ahead of exp the next token is fetched, and how long to wait for one.

Returns

tDeveloperTokenProvider

A provider to pass as developerToken. While it holds no usable token it rejects with what went wrong at the endpoint, as DeveloperTokenUnavailable; with a TypeError when url is relative and there is no document to resolve it against; and with the reason of a signal that aborts first.

Throws

TypeError if url is not http or https or carries credentials, or an option is not what it should be, when the provider is created. A relative URL with no document yet is left for the first call.