TIDAL SDK for Web

The TIDAL SDK for Web is designed for fast prototyping and development of web applications built on the TIDAL Developer Platform. It provides core functionality through a collection of easy-to-use software modules.

It acts as both a complement to and an extension of the TIDAL API. Note that some features are exclusive to the SDK, while others are available via both the API and the SDK.

TIDAL Player Web Components is a collection of web components designed to provide an easy way to integrate the TIDAL Player SDK into web applications. Instead of interacting with the low-level SDK directly, you can use these pre-built components to handle player functionality.

For practical implementation examples, refer to the demo/ application within the package directory.

The Event Producer uses a Job queue pattern to transport events from the application to the backend via a Transportation Layer (TL). The architecture is divided into three components:

1. Submitter: Triggered by sendEvent, it processes the event and stores it in the Queue.
2. Queue: A persistent memory data structure (using localforage with indexedDB to avoid blocking the main thread) containing submitted events that haven't been confirmed by the TL Consumer.
3. Scheduler: A background process that reads events from the Queue, sends them to the TL Consumer, and removes them once receipt is confirmed.

For the full technical specification, refer to the EventProducer specification.

To ensure seamless handling of timeouts, token upgrades, and automatic retries, always invoke credentialsProvider.getCredentials() every time you need a token.

Do not store the token yourself. The SDK is designed to manage the lifecycle of the oAuthTokens (including automatic session refresh) internally.

The @tidal-music/common module serves as a centralized repository for shared code used across multiple TIDAL SDK modules. Its primary purposes are:

1. Shared Types and Classes: It contains globally shared error and message classes/types used by various parts of the SDK.
2. Dependency Management: It acts as a base layer to prevent circular dependencies. While all other TIDAL modules can depend on common, common is strictly prohibited from depending on any other TIDAL module.

Because the Auth module relies on LocalStorage, standard Node.js environments will fail unless you handle credentials appropriately. You have two options for server-side usage:

1. Polyfill LocalStorage: Use a package like localstorage-polyfill to shim LocalStorage into the Node.js global scope.
2. Implement a CredentialsProvider: Implement the CredentialsProvider interface (defined in @tidal-music/common) and pass your custom provider into createAPIClient(myAuthProvider). This is the recommended approach if you need fine-grained control over the authentication flow.

If your application has already authenticated a user and you want to migrate those credentials into the @tidal-music/auth module:

1. Call init with the original clientId.
2. Call setCredentials providing the existing accessToken and refreshToken.
3. Call credentialsProvider.getCredentials() to obtain the token and continue using the SDK normally.

await auth.init({ clientId: '...' });
await auth.setCredentials({ accessToken: '...', refreshToken: '...' });
const { token } = await auth.credentialsProvider.getCredentials();

You can run tests across all packages from the root, or navigate to a specific package directory to run development commands.

To run all tests:

pnpm test

To work on a specific package (e.g., event-producer):

cd ./packages/event-producer
pnpm dev

# run tests in all packages
pnpm test

# go to the package dir you want to work on
cd ./packages/event-producer

pnpm dev

To use the TIDAL Auth module in your project, install it via npm or your preferred package manager:

npm install @tidal-music/auth

The development server runs at https://dev.tidal.com:5173. To ensure certificates are trusted locally, follow these one-time setup steps on your machine:

1. Update hosts file: Add an entry so dev.tidal.com resolves to your local machine:

   echo "127.0.0.1 dev.tidal.com" | sudo tee -a /etc/hosts

2. **Initialize certificates**: Run `pnpm dev` once. The first execution will prompt for `sudo` to allow `mkcert` to install its local root CA into your system trust store.

**Note for Corporate Proxies**: If you are behind a proxy, prefix the command with your proxy settings: `HTTPS_PROXY=... pnpm dev`.

**To reset certificates**: If you need to wipe and re-trust, run:
`mkcert -uninstall && rm -rf "$(mkcert -CAROOT)"`