========================
CODE SNIPPETS
========================
TITLE: Development Setup
DESCRIPTION: Commands for cloning the TIDAL SDK for Web repository, installing dependencies using pnpm, and running tests across all packages.

SOURCE: https://github.com/tidal-music/tidal-sdk-web/blob/main/README.md#_snippet_0

LANGUAGE: bash
CODE:
```
git clone git@github.com:tidal-music/tidal-sdk-web.git

cd ./tidal-sdk-web

# install deps
pnpm i

# run tests in all packages
pnpm test

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

pnpm dev
```

----------------------------------------

TITLE: Install TIDAL Auth SDK
DESCRIPTION: Instructions for installing the TIDAL Auth SDK using npm. This is the first step to integrate TIDAL authentication into your application.

SOURCE: https://github.com/tidal-music/tidal-sdk-web/blob/main/packages/auth/README.md#_snippet_0

LANGUAGE: bash
CODE:
```
npm install @tidal-music/auth
```

----------------------------------------

TITLE: Initialize and Send Event
DESCRIPTION: Demonstrates how to initialize the event producer with configuration options and send an event. Includes setup for app info, consent categories, credentials, platform details, and URIs. The `init` function starts the scheduler and restores events, and `sendEvent` dispatches an event with a consent category and payload. The `bus` function is also shown for listening to state changes.

SOURCE: https://github.com/tidal-music/tidal-sdk-web/blob/main/packages/event-producer/README.md#_snippet_0

LANGUAGE: typescript
CODE:
```
import { init, sendEvent, bus } from '@tidal-music/event-producer';
import { credentialsProvider } from './credentialsProvider';


async function main() {
  /**
   * Bootstrap the event producer by calling the init function.
   * This will start the scheduler and restore any previously stored events.
   * Note must be called before dispatchEvent.
   */
  await init({
    appInfo: { appName: 'YourApp', appVersion: '1.2.3' },
    // Used to initialize the blockedConsentCategories property
    blockedConsentCategories: {
      NECESSARY: false,
      PERFORMANCE: false,
      TARGETING: true,
    },
    // An access token provider, from @tidal-music/auth.
    credentialsProvider,
    // platform details
    platform: {
      browserName: 'Ice Hippo',
      browserVersion: '1.2.3',
      deviceVendor: 'Binocular',
      model: 'shyPhone',
      osName: 'Hov OS',
      version: '1.2.3',
    },
    // Optional Debug for integration purposes. Checks if consentCategory is missing.
    strictMode: false,
    // URI identifying the TL Consumer ingest endpoint.
    tlConsumerUri: '/api/event-batch',
    // URI for unauthorized event batches.
    tlPublicConsumerUri: '/api/public/event-batch',
  });

  // Now we can send events
  sendEvent({
    consentCategory: 'PERFORMANCE',
    name: 'listened_to_track',
    payload: {
      certifiedBanger: true,
    }
  })

  bus(()=>{
      console.log('Event producer outage state changed', )
  })
}
```

----------------------------------------

TITLE: Module Release Versioning
DESCRIPTION: Example of a package.json version entry, illustrating the format for module versioning following Semantic Versioning guidelines.

SOURCE: https://github.com/tidal-music/tidal-sdk-web/blob/main/README.md#_snippet_3

LANGUAGE: json
CODE:
```
{
  "version": "0.0.1"
}
```

----------------------------------------

TITLE: Install TIDAL Player
DESCRIPTION: Installs the TIDAL Player package using npm. This is the primary method to integrate the player into your web project.

SOURCE: https://github.com/tidal-music/tidal-sdk-web/blob/main/packages/player/README.md#_snippet_0

LANGUAGE: bash
CODE:
```
npm install @tidal-music/player
```

----------------------------------------

TITLE: Create New Module
DESCRIPTION: Executes a script to generate a new module within the TIDAL SDK for Web project, guiding the user through the process.

SOURCE: https://github.com/tidal-music/tidal-sdk-web/blob/main/README.md#_snippet_2

LANGUAGE: bash
CODE:
```
./bin/generate-module.sh
```

----------------------------------------

TITLE: Credentials JSON Structure
DESCRIPTION: Provides an example of the JSON structure required for setting credentials directly within the SDK. It includes fields like `clientId`, `requestedScopes`, `token`, and `expires`.

SOURCE: https://github.com/tidal-music/tidal-sdk-web/blob/main/packages/auth/examples/setting-credentials.html#_snippet_0

LANGUAGE: json
CODE:
```
{
  "clientId": "CLIENT_ID",
  "requestedScopes": [],
  "token": "ACCESS_TOKEN",
  "expires": 1701241737328
}
```

----------------------------------------

TITLE: Client Credentials Authentication
DESCRIPTION: Guides the process of authenticating using client credentials, suitable for server-to-server interactions or when accessing the TIDAL API directly. It involves initializing the SDK with client details and retrieving credentials.

SOURCE: https://github.com/tidal-music/tidal-sdk-web/blob/main/packages/auth/README.md#_snippet_1

LANGUAGE: javascript
CODE:
```
// 1. Initiate the process with clientId and clientSecret
await auth.init({
  clientId: "YOUR_CLIENT_ID",
  clientSecret: "YOUR_CLIENT_SECRET"
});

// 2. Obtain credentials containing a token
const credentials = await auth.credentialsProvider.getCredentials();
const token = credentials.token;

// 3. Make API calls with the token in the Authorization header
// fetch('https://api.tidal.com/some/endpoint', {
//   headers: {
//     'Authorization': `Bearer ${token}`
//   }
// });
```

----------------------------------------

TITLE: Combine tidal-play-trigger and tidal-video-view
DESCRIPTION: Demonstrates nesting the tidal-video-view component within a tidal-play-trigger to create an interactive element where clicking the video view initiates playback. This allows for custom styling and behavior of the playback trigger.

SOURCE: https://github.com/tidal-music/tidal-sdk-web/blob/main/packages/player-web-components/demo/index.html#_snippet_5

LANGUAGE: html
CODE:
```
<tidal-play-trigger product-id="23988566" product-type="video"> <tidal-video-view style="width:250px"></tidal-video-view> </tidal-play-trigger>
```

----------------------------------------

TITLE: Display Video with tidal-video-view Component
DESCRIPTION: The tidal-video-view component is used to output video data when a video is played. It can be configured with a video-id attribute to display a poster image when the video is not playing.

SOURCE: https://github.com/tidal-music/tidal-sdk-web/blob/main/packages/player-web-components/demo/index.html#_snippet_0

LANGUAGE: html
CODE:
```
<tidal-video-view style="width:500px"></tidal-video-view>
```

----------------------------------------

TITLE: Display Duration with tidal-duration-time
DESCRIPTION: The tidal-duration-time component shows the total duration of the current media product, formatted as (hh:)mm:ss. Similar to tidal-current-time, it adapts to its container and its color is controlled by currentColor.

SOURCE: https://github.com/tidal-music/tidal-sdk-web/blob/main/packages/player-web-components/demo/index.html#_snippet_3

LANGUAGE: html
CODE:
```
<tidal-duration-time></tidal-duration-time>
<tidal-duration-time>133.7</tidal-duration-time>
```

----------------------------------------

TITLE: Trigger Playback with tidal-play-trigger
DESCRIPTION: The tidal-play-trigger component serves as a button to initiate playback of a new item and also functions as a play/pause toggle. It requires 'product-id' and 'product-type' attributes to specify what to play. Any HTML element can be placed inside it to act as the trigger.

SOURCE: https://github.com/tidal-music/tidal-sdk-web/blob/main/packages/player-web-components/demo/index.html#_snippet_4

LANGUAGE: html
CODE:
```
<tidal-play-trigger product-id="243610992" product-type="track"> <button>Play track</button> </tidal-play-trigger>
<tidal-play-trigger product-id="143516331" product-type="video"> <em>Play video 🧐</em> </tidal-play-trigger>
```

----------------------------------------

TITLE: Show Playback Progress with tidal-progress-bar
DESCRIPTION: The tidal-progress-bar component visually indicates the elapsed progress of the currently playing media item. It is designed for smooth 60 FPS updates and adapts to the dimensions of its container. Its color is controlled by the CSS currentColor property.

SOURCE: https://github.com/tidal-music/tidal-sdk-web/blob/main/packages/player-web-components/demo/index.html#_snippet_1

LANGUAGE: html
CODE:
```
<tidal-progress-bar style="background-color:#aaa;width:500px;height:10px;color:cyan;border-radius:6px;overflow:hidden"></tidal-progress-bar>
```

----------------------------------------

TITLE: Display Current Time with tidal-current-time
DESCRIPTION: The tidal-current-time component displays the current playback time in a formatted (hh:)mm:ss string. It automatically fills its container and its color can be customized using the currentColor CSS property.

SOURCE: https://github.com/tidal-music/tidal-sdk-web/blob/main/packages/player-web-components/demo/index.html#_snippet_2

LANGUAGE: html
CODE:
```
<tidal-current-time></tidal-current-time>
```

----------------------------------------

TITLE: Build TIDAL Player Package
DESCRIPTION: Builds the TIDAL Player package using pnpm and Vite. The output is placed in the dist/ folder.

SOURCE: https://github.com/tidal-music/tidal-sdk-web/blob/main/packages/player/README.md#_snippet_1

LANGUAGE: bash
CODE:
```
pnpm build
```

----------------------------------------

TITLE: Run TIDAL Player Tests
DESCRIPTION: Executes the test suite for the TIDAL Player. Requires a .env file with TEST_USER containing base64 encoded user credentials.

SOURCE: https://github.com/tidal-music/tidal-sdk-web/blob/main/packages/player/README.md#_snippet_2

LANGUAGE: bash
CODE:
```
pnpm test
```

----------------------------------------

TITLE: Standard Local Linking Commands
DESCRIPTION: Standard commands for linking packages locally across different projects. Note that this can sometimes cause issues if package manager environments differ.

SOURCE: https://github.com/tidal-music/tidal-sdk-web/blob/main/packages/player/README.md#_snippet_4

LANGUAGE: bash
CODE:
```
pnpm link
```

LANGUAGE: bash
CODE:
```
yarn link
```

LANGUAGE: bash
CODE:
```
npm link
```

----------------------------------------

TITLE: Create API Client (Browser/Node.js)
DESCRIPTION: Demonstrates how to create an API client using `createAPIClient`. For Node.js, it outlines options for handling `LocalStorage` dependencies or implementing a custom `CredentialsProvider`.

SOURCE: https://github.com/tidal-music/tidal-sdk-web/blob/main/packages/api/README.md#_snippet_0

LANGUAGE: typescript
CODE:
```
import { createAPIClient } from '@tidal-music/sdk-web';

// For browser usage:
const apiClient = createAPIClient();

// For Node.js usage with a custom CredentialsProvider:
// import { CredentialsProvider } from '@tidal-music/sdk-web';
// class MyAuthProvider implements CredentialsProvider {
//   async getAccessToken(): Promise<string> {
//     // Implement logic to get token
//     return 'your_access_token';
//   }
//   async getRefreshToken(): Promise<string> {
//     // Implement logic to get refresh token
//     return 'your_refresh_token';
//   }
//   async setTokens(accessToken: string, refreshToken: string): Promise<void> {
//     // Implement logic to store tokens
//   }
// }
// const apiClient = createAPIClient(new MyAuthProvider());

```

----------------------------------------

TITLE: Setting Existing Credentials
DESCRIPTION: Describes how to migrate previously obtained access and refresh tokens into the auth module. This allows the SDK to manage the session seamlessly as if the user had logged in through the SDK.

SOURCE: https://github.com/tidal-music/tidal-sdk-web/blob/main/packages/auth/README.md#_snippet_4

LANGUAGE: javascript
CODE:
```
// 1. Initiate the SDK with your clientId
await auth.init({
  clientId: "YOUR_CLIENT_ID"
});

// 2. Set the previously obtained accessToken and refreshToken
await auth.setCredentials({
  accessToken: "PREVIOUS_ACCESS_TOKEN",
  refreshToken: "PREVIOUS_REFRESH_TOKEN"
});

// 3. Obtain credentials, the SDK will manage token refresh
const credentials = await auth.credentialsProvider.getCredentials();
const token = credentials.token;
```

----------------------------------------

TITLE: Update Workspace Dependencies
DESCRIPTION: Commands to recursively update all workspace dependencies to their latest versions and manage sub-dependencies.

SOURCE: https://github.com/tidal-music/tidal-sdk-web/blob/main/README.md#_snippet_1

LANGUAGE: bash
CODE:
```
pnpm recursive update --latest

# can also trim some sub-dependencies with:
pnpm update
pnpm dedupe
```

----------------------------------------

TITLE: TIDAL SDK Public Methods
DESCRIPTION: Provides an overview of the public methods available in the TIDAL Auth SDK. This documentation is generated from the SDK's source code and covers all functionalities for developers.

SOURCE: https://github.com/tidal-music/tidal-sdk-web/blob/main/packages/auth/README.md#_snippet_5

LANGUAGE: APIDOC
CODE:
```
TIDAL Auth SDK Public API:

Refer to the official documentation for detailed method signatures, parameters, return values, and examples:
https://tidal-music.github.io/tidal-sdk-web/modules/_tidal-music_auth.html

Key functionalities include:

- **Initialization**: `init(options)`
  - Initializes the SDK with configuration options like `clientId`, `clientSecret`, etc.

- **Credential Management**: `credentialsProvider.getCredentials()`
  - Retrieves the current valid access token. Handles automatic token refresh if necessary.

- **Login Flows**: 
  - `initializeLogin()`: Generates a URL for the Authorization Code Flow.
  - `finalizeLogin()`: Completes the Authorization Code Flow after user redirection.
  - `initializeDeviceLogin()`: Initiates the device-specific login flow, returning user code and verification URI.
  - `finalizeDeviceLogin()`: Polls the backend to complete the device login.

- **Manual Credential Setting**: `setCredentials(tokens)`
  - Manually sets existing access and refresh tokens.

- **Token Refresh**: The SDK automatically handles token refreshes when `getCredentials()` is called and the token has expired.

- **Error Handling**: The SDK is designed to manage common authentication errors, including token expiration and invalid credentials. Specific error codes and messages can be found in the detailed API documentation.
```

----------------------------------------

TITLE: Local Linking with File Protocol
DESCRIPTION: Manually configures a local link for the TIDAL Player package in a destination project's package.json using the file: protocol. This bypasses standard linking methods when projects use different package managers.

SOURCE: https://github.com/tidal-music/tidal-sdk-web/blob/main/packages/player/README.md#_snippet_3

LANGUAGE: json
CODE:
```
{
  "resolutions": {
    "@tidal-music/player": "file:/Users/<your-username>/dev/tidal-sdk-web/packages/player"
  }
}
```

----------------------------------------

TITLE: Resolve Cypress Binary Missing Error
DESCRIPTION: This snippet addresses the common Cypress error where the binary is missing. It explains potential causes related to CI/CD caching and provides commands to resolve the issue by either reinstalling the binary or ensuring proper cache management.

SOURCE: https://github.com/tidal-music/tidal-sdk-web/blob/main/__wiki__/Cypress-tests-are-failing.md#_snippet_0

LANGUAGE: text
CODE:
```
The cypress npm package is installed, but the Cypress binary is missing.

We expected the binary to be installed here: /home/runner/.cache/Cypress/13.13.2/Cypress/Cypress

Reasons it may be missing:

- You're caching 'node_modules' but are not caching this path: /home/runner/.cache/Cypress
- You ran 'npm install' at an earlier build step but did not persist: /home/runner/.cache/Cypress

Properly caching the binary will fix this error and avoid downloading and unzipping Cypress.

Alternatively, you can run 'cypress install' to download the binary again.
```

LANGUAGE: shell
CODE:
```
cypress install
```

----------------------------------------

TITLE: Playlist Creation
DESCRIPTION: Enables the creation of new playlists. Users can specify the playlist's name, a descriptive text, and its visibility (private or public).

SOURCE: https://github.com/tidal-music/tidal-sdk-web/blob/main/packages/api/examples/api-with-user.html#_snippet_1

LANGUAGE: APIDOC
CODE:
```
Create Playlist:
  Creates a new playlist for the authenticated user.
  Parameters:
    playlistName: string - The desired name for the new playlist.
    playlistDescription: string - A brief description for the playlist.
    playlistVisibility: enum (Private | Public) - Sets whether the playlist is visible to others.
  Returns: Details of the newly created playlist.
  Example:
    Create Playlist(
      playlistName="My Favorite Tracks",
      playlistDescription="A curated list of my top songs",
      playlistVisibility="Public"
    )
```

----------------------------------------

TITLE: Device Login Flow
DESCRIPTION: Explains the device login method for platforms with limited input capabilities. It involves displaying a user code and verification URI, which the user enters on another device to authorize the application.

SOURCE: https://github.com/tidal-music/tidal-sdk-web/blob/main/packages/auth/README.md#_snippet_3

LANGUAGE: javascript
CODE:
```
// 1. Initiate the SDK
await auth.init();

// 2. Initialize device login
const deviceAuthInfo = await auth.initializeDeviceLogin();

// Display deviceAuthInfo.userCode and deviceAuthInfo.verificationUri to the user
console.log(`Please visit ${deviceAuthInfo.verificationUri} and enter code: ${deviceAuthInfo.userCode}`);

// 3. Await user confirmation by polling the backend
await auth.finalizeDeviceLogin();

// 4. Retrieve token after successful device authorization
const credentials = await auth.credentialsProvider.getCredentials();
const token = credentials.token;
```

----------------------------------------

TITLE: Authentication Methods
DESCRIPTION: Handles user authentication flows, including initiating a login session and logging out. Requires a client ID and redirect URL for the login process.

SOURCE: https://github.com/tidal-music/tidal-sdk-web/blob/main/packages/api/examples/api-with-user.html#_snippet_0

LANGUAGE: APIDOC
CODE:
```
Login:
  Initiates the OAuth 2.0 authentication flow.
  Parameters:
    clientId: string - Your application's unique client identifier.
    redirectUrl: string - The URL to redirect to after successful authentication.
  Returns: A redirect to the Tidal authorization page.
  Related: Logout

Logout:
  Terminates the current user's session.
  Returns: Clears authentication tokens and redirects to a logged-out state.
  Related: Login
```

----------------------------------------

TITLE: Authorization Code Flow (User Login)
DESCRIPTION: Details the user login process using the Authorization Code Flow. This involves initiating login, redirecting the user to TIDAL for authentication, and then finalizing the login to obtain access tokens.

SOURCE: https://github.com/tidal-music/tidal-sdk-web/blob/main/packages/auth/README.md#_snippet_2

LANGUAGE: javascript
CODE:
```
// 1. Initiate the SDK
await auth.init();

// 2. For first login: Get login URL and redirect user
const loginUrl = auth.initializeLogin();
// Redirect user to loginUrl in a browser

// After user logs in and is redirected back to your app:
// 3. Finalize the login process
await auth.finalizeLogin();

// 4. Get credentials for API calls
const credentials = await auth.credentialsProvider.getCredentials();
const token = credentials.token;
```

----------------------------------------

TITLE: CSS Styling for Labels
DESCRIPTION: Applies basic block display and margin to label elements for consistent UI presentation. This rule ensures labels occupy their own line and have a small vertical space below them.

SOURCE: https://github.com/tidal-music/tidal-sdk-web/blob/main/packages/api/examples/api.html#_snippet_0

LANGUAGE: css
CODE:
```
label {
  display: block;
  margin-bottom: 5px;
}
```