### Install node-musickit-api

Source: https://musickit.js.org/getting-started

Commands to install the package using common JavaScript package managers.

```bash
npm install node-musickit-api
```

```bash
yarn add node-musickit-api
```

```bash
bun add node-musickit-api
```

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

### JSON Response Structure

Source: https://musickit.js.org/quickstart

Example of the JSON response returned by the search operation.

```json
{
  "status": 200,
  "data": {
    "nextOffset": 1,
    "results": {
      "albums": [
        {
          "id": "1893742002",
          "artistName": "aespa",
          "artwork": {
            "bgColor": "87d700",
            "height": 1400,
            "textColor1": "0a0d00",
            "textColor2": "15150b",
            "textColor3": "233500",
            "textColor4": "2c3c09",
            "url": "https://is1-ssl.mzstatic.com/image/thumb/Music221/v4/95/98/a0/.../{w}x{h}bb.jpg",
            "width": 1400
          },
          "genreNames": ["K-Pop", "Music", "Pop"],
          "isSingle": false,
          "name": "LEMONADE - The 2nd Album",
          "playParams": { "id": "1893742002", "kind": "album" },
          "recordLabel": "SM Entertainment",
          "releaseDate": "2026-05-29",
          "trackCount": 12,
          "upc": "888735955211",
          "url": "https://music.apple.com/us/album/lemonade-the-2nd-album/1893742002"
        }
      ],
      "songs": [
        {
          "id": "1893742010",
          "albumName": "LEMONADE - The 2nd Album",
          "artistName": "aespa",
          "artwork": {
            "bgColor": "87d700",
            "height": 1400,
            "textColor1": "0a0d00",
            "textColor2": "15150b",
            "textColor3": "233500",
            "textColor4": "2c3c09",
            "url": "https://is1-ssl.mzstatic.com/image/thumb/Music221/v4/95/98/a0/.../{w}x{h}bb.jpg",
            "width": 1400
          },
          "durationInMillis": 187000,
          "genreNames": ["K-Pop", "Music", "Pop"],
          "hasLyrics": true,
          "isrc": "KRA302600098",
          "name": "LEMONADE",
          "playParams": { "id": "1893742010", "kind": "song" },
          "releaseDate": "2026-05-28",
          "trackNumber": 2,
          "url": "https://music.apple.com/us/album/lemonade/1893742002?i=1893742010"
        }
      ]
    }
  },
  "error": null
}
```

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

### Raw API response structure

Source: https://musickit.js.org/search

Example of the raw, unprocessed response format from the Apple Music API.

```json
{
  "status": 200,
  "data": {
    "results": {
      "artists": {
        "href": "/v1/catalog/us/search?term=Aespa&types=artists&limit=1",
        "next": "/v1/catalog/us/search?offset=1&term=Aespa&types=artists",
        "data": [
          {
            "id": "1540251304",
            "type": "artists",
            "href": "/v1/catalog/us/artists/1540251304",
            "attributes": {
              "name": "aespa",
              "genreNames": ["K-Pop"],
              "url": "https://music.apple.com/us/artist/aespa/1540251304"
            },
            "relationships": {
              "albums": {
                "href": "/v1/catalog/us/artists/1540251304/albums",
                "next": "/v1/catalog/us/artists/1540251304/albums?offset=25",
                "data": [
                  { "id": "1567326687", "type": "albums", "href": "/v1/catalog/us/albums/1567326687" }
                ]
              }
            }
          }
        ]
      }
    }
  },
  "error": null
}
```

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

### musicKit.albums.getByUPC(storefront, upc, raw?)

Source: https://musickit.js.org/resources/albums

Fetches an album by its UPC barcode. Returns the same data structure as the get() method.

```APIDOC
## musicKit.albums.getByUPC(storefront, upc, raw?)

### Description
Fetch an album by its UPC barcode.

### Parameters
- **storefront** (string) - Required - The storefront identifier (e.g., "us").
- **upc** (string) - Required - The UPC barcode of the album.
- **raw** (boolean) - Optional - If true, returns the raw API response structure.

### Request Example
```javascript
const album = await musicKit.albums.getByUPC("us", "888735955211");
```
```

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

### Parsed search response structure

Source: https://musickit.js.org/search

Example of the structured JSON object returned by the search method.

```json
{
  "status": 200,
  "data": {
    "nextOffset": 1,
    "results": {
      "songs": [
        {
          "id": "1893742010",
          "name": "LEMONADE",
          "artistName": "aespa",
          "albumName": "LEMONADE - The 2nd Album",
          "durationInMillis": 187000,
          "genreNames": ["K-Pop", "Music", "Pop"],
          "hasLyrics": true,
          "isrc": "KRA302600098",
          "releaseDate": "2026-05-28",
          "trackNumber": 2,
          "url": "https://music.apple.com/us/album/lemonade/1893742002?i=1893742010",
          "artwork": {
            "bgColor": "87d700",
            "height": 1400,
            "url": "https://is1-ssl.mzstatic.com/.../{w}x{h}bb.jpg",
            "width": 1400
          },
          "playParams": { "id": "1893742010", "kind": "song" },
          "relationships": {
            "albums": [{ "id": "1893742002", "type": "albums", "href": "/v1/catalog/us/albums/1893742002" }],
            "artists": [{ "id": "1540251304", "type": "artists", "href": "/v1/catalog/us/artists/1540251304" }]
          }
        }
      ],
      "albums": [ /* ... same shape but with album fields */ ]
    }
  },
  "error": null
}
```

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

### Configure MusicKit with Local File

Source: https://musickit.js.org/getting-started

Alternative approach for initializing the client by reading the private key from a local file.

```javascript
// ✅ Alternative: read from a gitignored file
import { MusicKit } from "node-musickit-api"


const p8 = await Bun.file("./AuthKey_XXXXXXXX.p8").text()


const musicKit = new MusicKit({
  key: {
    id: "YOUR_KEY_ID",
    teamId: "YOUR_TEAM_ID",
    p8
  }
})
```

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

### Configure MusicKit with Environment Variables

Source: https://musickit.js.org/getting-started

Recommended approach for initializing the MusicKit client using environment variables to keep credentials secure.

```javascript
// ✅ Recommended: environment variables
import { MusicKit } from "node-musickit-api"


const musicKit = new MusicKit({
  key: {
    id: process.env.MUSICKIT_KEY_ID!,
    teamId: process.env.MUSICKIT_TEAM_ID!,
    p8: process.env.MUSICKIT_P8!
  }
})
```

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

### Initialize and Search with MusicKit

Source: https://musickit.js.org/quickstart

Initializes the client with credentials and performs a search for songs and albums.

```typescript
import { MusicKit } from "node-musickit-api"


const musicKit = new MusicKit({
  key: {
    id: process.env.MUSICKIT_KEY_ID!,
    teamId: process.env.MUSICKIT_TEAM_ID!,
    p8: process.env.MUSICKIT_P8!
  }
})


// Authenticate first
await musicKit.auth()


// Search for songs + albums
const searchResults = await musicKit.search("us", {
  term: "Lemonade aespa",
  types: ["songs", "albums"],
  limit: 1
})


console.log(searchResults)
```

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

### musicKit.storefronts.getAll(props?, raw?)

Source: https://musickit.js.org/resources/storefronts

Retrieves a list of all available storefronts. Supports optional filtering via props and raw data format.

```APIDOC
## musicKit.storefronts.getAll(props?, raw?)

### Description
List all available storefronts. You can pass optional props to paginate or configure the response, and a raw flag to retrieve the raw API response structure.

### Parameters
- **props** (object) - Optional - Configuration object for filtering (e.g., { limit: 5, offset: 0 })
- **raw** (boolean) - Optional - If true, returns the raw API response structure.

### Example
```javascript
const storefronts = await musicKit.storefronts.getAll();
const raw = await musicKit.storefronts.getAll({}, true);
const filtered = await musicKit.storefronts.getAll({ limit: 5, offset: 0 });
```
```

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

### Retrieve all storefronts in raw format

Source: https://musickit.js.org/resources/storefronts

Fetches all storefronts returning the raw API response structure.

```javascript
const raw = await musicKit.storefronts.getAll({}, true)
```

```json
{
  "status": 200,
  "data": [
    {
      "id": "us",
      "type": "storefronts",
      "href": "/v1/storefronts/us",
      "attributes": {
        "explicitContentPolicy": "allowed",
        "name": "United States",
        "defaultLanguageTag": "en-US",
        "supportedLanguageTags": ["en-US", "es-MX"]
      }
    }
  ],
  "error": null
}
```

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

### musicKit.storefronts.get(storefront, props?, raw?)

Source: https://musickit.js.org/resources/storefronts

Fetches a single storefront by its unique identifier.

```APIDOC
## musicKit.storefronts.get(storefront, props?, raw?)

### Description
Fetch a single storefront by its identifier (e.g., "us", "gb", "jp").

### Parameters
- **storefront** (string) - Required - The identifier of the storefront.
- **props** (object) - Optional - Configuration object.
- **raw** (boolean) - Optional - If true, returns the raw API response structure.

### Example
```javascript
const storefront = await musicKit.storefronts.get("us");
const raw = await musicKit.storefronts.get("us", {}, true);
```
```

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

### Fetch a single storefront in raw format

Source: https://musickit.js.org/resources/storefronts

Retrieves a single storefront returning the raw API response structure.

```javascript
const raw = await musicKit.storefronts.get("us", {}, true)
```

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

### Retrieve all storefronts

Source: https://musickit.js.org/resources/storefronts

Fetches a list of all available storefronts.

```javascript
const storefronts = await musicKit.storefronts.getAll()
```

```json
{
  "status": 200,
  "data": [
    {
      "id": "us",
      "explicitContentPolicy": "allowed",
      "name": "United States",
      "defaultLanguageTag": "en-US",
      "supportedLanguageTags": ["en-US", "es-MX"]
    },
    {
      "id": "gb",
      "explicitContentPolicy": "allowed",
      "name": "United Kingdom",
      "defaultLanguageTag": "en-GB",
      "supportedLanguageTags": ["en-GB"]
    }
  ],
  "error": null
}
```

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

### Resource Methods

Source: https://musickit.js.org/resources

Methods available for accessing catalog resources through the MusicKit instance.

```APIDOC
## Resource Methods

### Description
Access catalog resources using the `musicKit` instance getters. All methods accept an optional `raw` boolean flag as the last argument to toggle between parsed and raw API response shapes.

### Available Resources
- **Songs**: `get(storefront, id)`, `getByISRC(storefront, isrc)`
- **Albums**: `get(storefront, id)`, `getByUPC(storefront, upc)`
- **Artists**: `get(storefront, id)`
- **Music Videos**: `get(storefront, id)`, `getByISRC(storefront, isrc)`
- **Storefronts**: `getAll(props?)`, `get(storefront, props?)`

### Result Wrapper
All methods return an object with the following structure:
- **status** (number) - HTTP status code
- **data** (T) - Response payload
- **error** (string | null) - Error message if the request failed
```

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

### Authenticate MusicKit Client

Source: https://musickit.js.org/getting-started

Initializes the authentication process by generating a JWT. Must be called before making any API requests.

```javascript
await musicKit.auth()
```

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

### Define Storefront request properties

Source: https://musickit.js.org/reference/types

Configuration types for storefront resource requests, including language, inclusion, and pagination parameters.

```typescript

type GetStorefrontsProps = {
  l?: string       // language tag
  include?: string[]  // additional resources to include
  extend?: string[]   // additional fields to extend
}


type GetAllStorefrontsProps = GetStorefrontsProps & {
  limit?: number   // results per page
  offset?: number  // pagination offset
}

```

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

### musicKit.musicVideos.get(storefront, id, raw?)

Source: https://musickit.js.org/resources/music-videos

Fetches a music video by its Apple Music catalog ID. The optional raw parameter returns the full API response structure.

```APIDOC
## musicKit.musicVideos.get(storefront, id, raw?)

### Description
Fetch a music video by its Apple Music catalog ID.

### Parameters
- **storefront** (string) - Required - The storefront identifier (e.g., "us").
- **id** (string) - Required - The Apple Music catalog ID of the music video.
- **raw** (boolean) - Optional - If true, returns the raw API response structure.
```

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

### Accessing Catalog Resources

Source: https://musickit.js.org/resources

Use lazy-loaded getters on the MusicKit instance to access specific catalog resources.

```javascript
musicKit.songs        // SongsResource
musicKit.albums       // AlbumsResource
musicKit.artists      // ArtistsResource
musicKit.musicVideos  // MusicVideosResource
musicKit.storefronts  // StorefrontsResource
```

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

### Fetch a single storefront

Source: https://musickit.js.org/resources/storefronts

Retrieves details for a specific storefront using its identifier.

```javascript
const storefront = await musicKit.storefronts.get("us")
```

```json
{
  "status": 200,
  "data": [
    {
      "id": "us",
      "explicitContentPolicy": "allowed",
      "name": "United States",
      "defaultLanguageTag": "en-US",
      "supportedLanguageTags": ["en-US", "es-MX"]
    }
  ],
  "error": null
}
```

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

### Fetch a music video by ID (Raw)

Source: https://musickit.js.org/resources/music-videos

Retrieves the raw response structure for a music video by ID.

```javascript
const raw = await musicKit.musicVideos.get("us", "1896856900", true)
```

```json
{
  "status": 200,
  "data": [
    {
      "id": "1896856900",
      "type": "music-videos",
      "href": "/v1/catalog/us/music-videos/1896856900",
      "attributes": {
        "artistName": "aespa",
        "artwork": { "bgColor": "1f2e3e", "height": 1080, "width": 1684, "url": "..." },
        "durationInMillis": 187030,
        "genreNames": ["K-Pop"],
        "has4K": false,
        "hasHDR": false,
        "isrc": "KRZ262600092",
        "name": "LEMONADE",
        "playParams": { "id": "1896856900", "kind": "musicVideo" },
        "previews": [{ "artwork": {}, "hlsUrl": "...", "url": "..." }],
        "releaseDate": "2026-05-29",
        "url": "https://music.apple.com/us/music-video/lemonade/1896856900"
      },
      "relationships": {
        "albums": { "href": "/v1/catalog/us/music-videos/1896856900/albums", "data": [] },
        "artists": {
          "href": "/v1/catalog/us/music-videos/1896856900/artists",
          "data": [{ "id": "1540251304", "type": "artists", "href": "/v1/catalog/us/artists/1540251304" }]
        }
      }
    }
  ],
  "error": null
}
```

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

### Ignore Key Files in Git

Source: https://musickit.js.org/getting-started

Pattern to add to your .gitignore file to prevent accidental exposure of private key files.

```text
AuthKey_*.p8
```

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

### Fetch an artist by ID

Source: https://musickit.js.org/resources/artists

Retrieves artist details using the storefront and catalog ID.

```javascript
const artist = await musicKit.artists.get("us", "1540251304")
```

```json
{
  "status": 200,
  "data": [
    {
      "id": "1540251304",
      "artwork": {
        "bgColor": "d8e953",
        "height": 4000,
        "textColor1": "090d1c",
        "textColor2": "182330",
        "textColor3": "333927",
        "textColor4": "3f4b37",
        "url": "https://is1-ssl.mzstatic.com/image/thumb/AMCArtistImages211/v4/.../{w}x{h}bb.jpg",
        "width": 4000
      },
      "editorialNotes": {
        "name": "aespa's LIVE TOUR - SYNK : PARALLEL LINE Set List",
        "short": "aespa travel together on the SYNK : PARALLEL LINE tour.",
        "tagline": "Set List: aespa"
      },
      "genreNames": ["K-Pop"],
      "name": "aespa",
      "url": "https://music.apple.com/us/artist/aespa/1540251304",
      "relationships": {
        "albums": [
          { "id": "1567326687", "type": "albums", "href": "/v1/catalog/us/albums/1567326687" },
          { "id": "1540251303", "type": "albums", "href": "/v1/catalog/us/albums/1540251303" },
          { "id": "1893742002", "type": "albums", "href": "/v1/catalog/us/albums/1893742002" }
        ]
      }
    }
  ],
  "error": null
}
```

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

### Define MusicKitProps

Source: https://musickit.js.org/reference/types

Configuration object required for initializing MusicKit with Apple developer credentials.

```typescript
type MusicKitProps = {
  key: {
    id: string     // Apple Music Key ID
    teamId: string // Apple Developer Team ID
    p8: string     // Contents of the .p8 private key file (including headers)
  }
}
```

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

### musicKit.search(storefront, params, [includeRawResponse])

Source: https://musickit.js.org/search

Queries the Apple Music catalog based on the provided search term and resource types.

```APIDOC
## musicKit.search(storefront, params, [includeRawResponse])

### Description
Queries the Apple Music catalog for resources matching the specified term. Supports pagination and optional raw response format.

### Parameters
- **storefront** (string) - Required - Apple Music storefront code (e.g., "us", "gb", "jp").
- **params.term** (string) - Required - Search query string.
- **params.types** (SearchType[]) - Required - Resource types to include (e.g., "songs", "albums", "artists").
- **params.limit** (number) - Optional - Max results per type (1–25, default 10).
- **params.offset** (number) - Optional - Pagination offset.
- **params.l** (string) - Optional - Language tag (e.g., "en-us").
- **params.with** (string[]) - Optional - Additional resources to include.
- **includeRawResponse** (boolean) - Optional - Pass true to get the unprocessed Apple Music API response.

### Request Example
```javascript
const result = await musicKit.search("us", {
  term: "Lemonade aespa",
  types: ["songs", "albums"]
});
```

### Response
#### Success Response (200)
- **data** (object) - The search results containing the requested resources and pagination metadata.
```

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

### Fetch a song by catalog ID in raw format

Source: https://musickit.js.org/resources/songs

Retrieves the raw API response for a song by setting the third parameter to true.

```javascript
const raw = await musicKit.songs.get("us", "1893742010", true)
```

```json
{
  "status": 200,
  "data": [
    {
      "id": "1893742010",
      "type": "songs",
      "href": "/v1/catalog/us/songs/1893742010",
      "attributes": {
        "albumName": "LEMONADE - The 2nd Album",
        "artistName": "aespa",
        "artwork": { "bgColor": "87d700", "height": 1400, "width": 1400, "url": "..." },
        "durationInMillis": 187000,
        "genreNames": ["K-Pop", "Music", "Pop"],
        "hasLyrics": true,
        "isrc": "KRA302600098",
        "name": "LEMONADE",
        "playParams": { "id": "1893742010", "kind": "song" },
        "releaseDate": "2026-05-28",
        "trackNumber": 2
      },
      "relationships": {
        "albums": {
          "href": "/v1/catalog/us/songs/1893742010/albums",
          "data": [{ "id": "1893742002", "type": "albums", "href": "/v1/catalog/us/albums/1893742002" }]
        },
        "artists": {
          "href": "/v1/catalog/us/songs/1893742010/artists",
          "data": [{ "id": "1540251304", "type": "artists", "href": "/v1/catalog/us/artists/1540251304" }]
        }
      }
    }
  ],
  "error": null
}
```

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

### Fetch a music video by ID

Source: https://musickit.js.org/resources/music-videos

Retrieves music video details using the storefront and catalog ID.

```javascript
const mv = await musicKit.musicVideos.get("us", "1896856900")
```

```json
{
  "status": 200,
  "data": [
    {
      "id": "1896856900",
      "artistName": "aespa",
      "artwork": {
        "bgColor": "1f2e3e",
        "height": 1080,
        "textColor1": "cbdce8",
        "textColor2": "acc6d9",
        "textColor3": "acbdc9",
        "textColor4": "93aabd",
        "url": "https://is1-ssl.mzstatic.com/image/thumb/Video211/v4/.../{w}x{h}mv.jpg",
        "width": 1684
      },
      "durationInMillis": 187030,
      "genreNames": ["K-Pop"],
      "has4K": false,
      "hasHDR": false,
      "isrc": "KRZ262600092",
      "name": "LEMONADE",
      "playParams": { "id": "1896856900", "kind": "musicVideo" },
      "previews": [
        {
          "artwork": {
            "bgColor": "1f2e3e",
            "height": 1080,
            "url": "https://is1-ssl.mzstatic.com/image/thumb/Video211/v4/.../{w}x{h}bb.jpg",
            "width": 1684
          },
          "hlsUrl": "https://play-edge.itunes.apple.com/.../playlist.m3u8",
          "url": "https://video-ssl.itunes.apple.com/.../mzvf_....640x480.h264lc.U.p.m4v"
        }
      ],
      "releaseDate": "2026-05-29",
      "url": "https://music.apple.com/us/music-video/lemonade/1896856900",
      "relationships": {
        "albums": [],
        "artists": [
          { "id": "1540251304", "type": "artists", "href": "/v1/catalog/us/artists/1540251304" }
        ]
      }
    }
  ],
  "error": null
}
```

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

### musicKit.albums.get(storefront, id, raw?)

Source: https://musickit.js.org/resources/albums

Fetches an album by its Apple Music catalog ID. The raw parameter can be set to true to return the raw API response.

```APIDOC
## musicKit.albums.get(storefront, id, raw?)

### Description
Fetch an album by its Apple Music catalog ID.

### Parameters
- **storefront** (string) - Required - The storefront identifier (e.g., "lv").
- **id** (string) - Required - The Apple Music catalog ID of the album.
- **raw** (boolean) - Optional - If true, returns the raw API response structure.

### Request Example
```javascript
const album = await musicKit.albums.get("lv", "1893742002");
```
```

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

### musicKit.artists.get(storefront, id, raw?)

Source: https://musickit.js.org/resources/artists

Fetches an artist by their Apple Music catalog ID. The optional raw parameter allows retrieving the raw API response structure.

```APIDOC
## musicKit.artists.get(storefront, id, raw?)

### Description
Fetch an artist by their Apple Music catalog ID.

### Parameters
- **storefront** (string) - Required - The storefront identifier (e.g., "us").
- **id** (string) - Required - The Apple Music catalog ID of the artist.
- **raw** (boolean) - Optional - If true, returns the raw API response structure.

### Usage Example
```javascript
const artist = await musicKit.artists.get("us", "1540251304");
```

### Raw Usage Example
```javascript
const raw = await musicKit.artists.get("us", "1540251304", true);
```
```

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

### Fetch Album by UPC

Source: https://musickit.js.org/resources/albums

Retrieves album details using a storefront and UPC barcode.

```javascript
const album = await musicKit.albums.getByUPC("us", "888735955211")
```

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

### Fetch Album by ID

Source: https://musickit.js.org/resources/albums

Retrieves album details using a storefront and catalog ID. The response includes structured album attributes and relationships.

```javascript
const album = await musicKit.albums.get("lv", "1893742002")
```

```json
{
  "status": 200,
  "data": [
    {
      "id": "1893742002",
      "artistName": "aespa",
      "artwork": {
        "bgColor": "87d700",
        "height": 1400,
        "textColor1": "0a0d00",
        "textColor2": "15150b",
        "textColor3": "233500",
        "textColor4": "2c3c09",
        "url": "https://is1-ssl.mzstatic.com/image/thumb/Music221/v4/95/98/a0/.../{w}x{h}bb.jpg",
        "width": 1400
      },
      "copyright": "℗ 2026 SM Entertainment",
      "editorialNotes": {
        "short": "Doubling down on the electronic bangers that made them famous.",
        "tagline": "New Album"
      },
      "genreNames": ["K-Pop", "Music", "Pop"],
      "isCompilation": false,
      "isComplete": true,
      "isMasteredForItunes": false,
      "isSingle": false,
      "name": "LEMONADE - The 2nd Album",
      "playParams": { "id": "1893742002", "kind": "album" },
      "recordLabel": "SM Entertainment",
      "releaseDate": "2026-05-29",
      "trackCount": 12,
      "upc": "888735955211",
      "url": "https://music.apple.com/lv/album/lemonade-the-2nd-album/1893742002",
      "relationships": {
        "artists": [
          { "id": "1540251304", "type": "artists", "href": "/v1/catalog/lv/artists/1540251304" }
        ],
        "tracks": [
          {
            "id": "1893742004",
            "type": "songs",
            "href": "/v1/catalog/lv/songs/1893742004",
            "attributes": {
              "albumName": "LEMONADE - The 2nd Album",
              "artistName": "aespa",
              "durationInMillis": 196000,
              "name": "WDA (Whole Different Animal) (feat. G-DRAGON)",
              "trackNumber": 1
            }
          }
        ]
      }
    }
  ],
  "error": null
}
```

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

### Result Wrapper Structure

Source: https://musickit.js.org/resources

All resource methods return a consistent wrapper containing status, data, and error fields.

```javascript
{
  status: number       // HTTP status code
  data: T              // Response payload (array of items or search result)
  error: string | null // Error message if the request failed
}
```

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

### musicKit.musicVideos.getByISRC(storefront, isrc, raw?)

Source: https://musickit.js.org/resources/music-videos

Fetches a music video by its International Standard Recording Code (ISRC).

```APIDOC
## musicKit.musicVideos.getByISRC(storefront, isrc, raw?)

### Description
Fetch a music video by its international standard recording code.

### Parameters
- **storefront** (string) - Required - The storefront identifier (e.g., "us").
- **isrc** (string) - Required - The ISRC code of the music video.
- **raw** (boolean) - Optional - If true, returns the raw API response structure.
```

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

### Filter storefront results

Source: https://musickit.js.org/resources/storefronts

Applies pagination or configuration options to the storefront list request.

```javascript
const result = await musicKit.storefronts.getAll({ limit: 5, offset: 0 })
```

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

### Fetch a music video by ISRC

Source: https://musickit.js.org/resources/music-videos

Retrieves music video details using the storefront and ISRC.

```javascript
const mv = await musicKit.musicVideos.getByISRC("us", "KRZ262600092")
```

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

### musicKit.songs.getByISRC(storefront, isrc, raw?)

Source: https://musickit.js.org/resources/songs

Fetches a song by its international standard recording code (ISRC).

```APIDOC
## musicKit.songs.getByISRC(storefront, isrc, raw?)

### Description
Fetch a song by its international standard recording code.

### Parameters
- **storefront** (string) - Required - The storefront identifier (e.g., "us").
- **isrc** (string) - Required - The ISRC of the song.
- **raw** (boolean) - Optional - If true, returns the raw API response structure.
```

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

### Paginate search results

Source: https://musickit.js.org/search

Use the nextOffset value from a previous response to fetch subsequent pages of results.

```javascript
const page1 = await musicKit.search("us", {
  term: "aespa",
  types: ["albums"],
  limit: 5
})


const nextOffset = page1.data.nextOffset // e.g. 5


if (nextOffset !== null) {
  const page2 = await musicKit.search("us", {
    term: "aespa",
    types: ["albums"],
    limit: 5,
    offset: nextOffset
  })
}
```

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

### Fetch a song by catalog ID

Source: https://musickit.js.org/resources/songs

Retrieves song details using the storefront and catalog ID. The response provides a structured object containing metadata like album, artist, and artwork.

```javascript
const song = await musicKit.songs.get("us", "1893742010")
```

```json
{
  "status": 200,
  "data": [
    {
      "id": "1893742010",
      "albumName": "LEMONADE - The 2nd Album",
      "artistName": "aespa",
      "artwork": {
        "bgColor": "87d700",
        "height": 1400,
        "textColor1": "0a0d00",
        "textColor2": "15150b",
        "textColor3": "233500",
        "textColor4": "2c3c09",
        "url": "https://is1-ssl.mzstatic.com/image/thumb/Music221/v4/95/98/a0/.../{w}x{h}bb.jpg",
        "width": 1400
      },
      "composerName": "Lewis Jankel, Jordan Shaw, Taylor Upsahl & Cyrus Villanueva",
      "discNumber": 1,
      "durationInMillis": 187000,
      "genreNames": ["K-Pop", "Music", "Pop"],
      "hasLyrics": true,
      "isAppleDigitalMaster": false,
      "isrc": "KRA302600098",
      "name": "LEMONADE",
      "playParams": { "id": "1893742010", "kind": "song" },
      "previews": [{ "url": "https://audio-ssl.itunes.apple.com/..." }],
      "releaseDate": "2026-05-28",
      "trackNumber": 2,
      "url": "https://music.apple.com/us/album/lemonade/1893742002?i=1893742010",
      "relationships": {
        "albums": [
          { "id": "1893742002", "type": "albums", "href": "/v1/catalog/us/albums/1893742002" }
        ],
        "artists": [
          { "id": "1540251304", "type": "artists", "href": "/v1/catalog/us/artists/1540251304" }
        ]
      }
    }
  ],
  "error": null
}
```

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

### musicKit.songs.get(storefront, id, raw?)

Source: https://musickit.js.org/resources/songs

Fetches a song by its Apple Music catalog ID. The raw parameter can be used to return the raw API response structure.

```APIDOC
## musicKit.songs.get(storefront, id, raw?)

### Description
Fetch a song by its Apple Music catalog ID.

### Parameters
- **storefront** (string) - Required - The storefront identifier (e.g., "us").
- **id** (string) - Required - The Apple Music catalog ID of the song.
- **raw** (boolean) - Optional - If true, returns the raw API response structure.
```

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

### Perform a catalog search

Source: https://musickit.js.org/search

Queries the catalog for specific terms and resource types.

```javascript
const result = await musicKit.search("us", {
  term: "Lemonade aespa",
  types: ["songs", "albums"]
})
```

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

### Define Shared Resource Interfaces

Source: https://musickit.js.org/reference/types

Common interfaces used across various MusicKit resources, including artwork, editorial notes, and playback parameters.

```typescript
interface Artwork {
  bgColor: string
  height: number
  textColor1: string
  textColor2: string
  textColor3: string
  textColor4: string
  url: string   // contains {w} and {h} placeholders
  width: number
}


interface EditorialNotes {
  name?: string
  short: string
  standard: string
  tagline: string
}


interface Preview {
  url: string
}


interface PlayParams {
  id: string
  kind: string
}
```

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

### Define Per-Resource Relationship Maps

Source: https://musickit.js.org/reference/types

Maps specific resources to their available relationships.

```typescript
type SongRelationships = Partial<Record<"albums" | "artists", GenericRelationship>>


type AlbumRelationships = {
  artists: GenericRelationship
  tracks: TrackRelationship
}


type ArtistRelationships = {
  albums: GenericRelationship
}


type MusicVideoRelationships = Partial<Record<"albums" | "artists", GenericRelationship>>
```

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

### Fetch raw artist data

Source: https://musickit.js.org/resources/artists

Retrieves the raw API response for an artist by setting the raw parameter to true.

```javascript
const raw = await musicKit.artists.get("us", "1540251304", true)
```

```json
{
  "status": 200,
  "data": [
    {
      "id": "1540251304",
      "type": "artists",
      "href": "/v1/catalog/us/artists/1540251304",
      "attributes": {
        "artwork": { "bgColor": "d8e953", "height": 4000, "width": 4000, "url": "..." },
        "editorialNotes": {
          "name": "aespa's LIVE TOUR - SYNK : PARALLEL LINE Set List",
          "short": "aespa travel together on the SYNK : PARALLEL LINE tour.",
          "tagline": "Set List: aespa"
        },
        "genreNames": ["K-Pop"],
        "name": "aespa",
        "url": "https://music.apple.com/us/artist/aespa/1540251304"
      },
      "relationships": {
        "albums": {
          "href": "/v1/catalog/us/artists/1540251304/albums",
          "next": "/v1/catalog/us/artists/1540251304/albums?offset=25",
          "data": [
            { "id": "1567326687", "type": "albums", "href": "/v1/catalog/us/albums/1567326687" },
            { "id": "1540251303", "type": "albums", "href": "/v1/catalog/us/albums/1540251303" }
          ]
        }
      }
    }
  ],
  "error": null
}
```

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

### Fetch Raw Album Data

Source: https://musickit.js.org/resources/albums

Retrieves the raw API response for an album by setting the third parameter to true.

```javascript
const raw = await musicKit.albums.get("lv", "1893742002", true)
```

```json
{
  "status": 200,
  "data": [
    {
      "id": "1893742002",
      "type": "albums",
      "href": "/v1/catalog/lv/albums/1893742002",
      "attributes": {
        "artistName": "aespa",
        "artwork": { "bgColor": "87d700", "height": 1400, "width": 1400, "url": "..." },
        "copyright": "℗ 2026 SM Entertainment",
        "isCompilation": false,
        "isComplete": true,
        "isSingle": false,
        "name": "LEMONADE - The 2nd Album",
        "playParams": { "id": "1893742002", "kind": "album" },
        "recordLabel": "SM Entertainment",
        "releaseDate": "2026-05-29",
        "trackCount": 12,
        "upc": "888735955211"
      },
      "relationships": {
        "artists": {
          "href": "/v1/catalog/lv/albums/1893742002/artists",
          "data": [{ "id": "1540251304", "type": "artists", "href": "/v1/catalog/lv/artists/1540251304" }]
        },
        "tracks": {
          "href": "/v1/catalog/lv/albums/1893742002/tracks",
          "data": [
            {
              "id": "1893742004",
              "type": "songs",
              "href": "/v1/catalog/lv/songs/1893742004",
              "attributes": {
                "artistName": "aespa",
                "durationInMillis": 196000,
                "name": "WDA (Whole Different Animal) (feat. G-DRAGON)",
                "trackNumber": 1
              }
            }
          ]
        }
      }
    }
  ],
  "error": null
}
```

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

### Fetch Song by ID

Source: https://musickit.js.org/quickstart

Retrieves a specific song using its unique identifier.

```typescript
const song = await musicKit.songs.get("us", "1893742010")


console.log(song.data[0].name)       // "LEMONADE"
console.log(song.data[0].artistName) // "aespa"
console.log(song.data[0].hasLyrics)  // true
```

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

### Retrieve raw API response

Source: https://musickit.js.org/search

Pass true as the third argument to receive the unprocessed Apple Music API response.

```javascript
const raw = await musicKit.search("us", { term: "aespa", types: ["artists"], limit: 1 }, true)
```

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

### Define SearchParams

Source: https://musickit.js.org/reference/types

Configuration object for defining search queries, including pagination and resource filtering.

```typescript
type SearchParams = {
  term: string               // Search query
  types: SearchType[]        // Resource types to search
  l?: string                 // Language tag (e.g. "en-us")
  limit?: 1 | 2 | ... | 25  // Results per type (max 25)
  offset?: number            // Pagination offset
  with?: string[]            // Additional resources to include
}
```

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

### Fetch a song by ISRC

Source: https://musickit.js.org/resources/songs

Retrieves song details using the international standard recording code.

```javascript
const song = await musicKit.songs.getByISRC("us", "KRA302600098")
```

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

### Define Storefront and StorefrontRaw types

Source: https://musickit.js.org/reference/types

Defines the structure for storefront data, including a raw interface that preserves nested API response attributes.

```typescript

type Storefront = {
  id: string
  explicitContentPolicy: string   // "allowed" | "denied" | "opt-in"
  name: string                    // e.g. "United States"
  defaultLanguageTag: string      // e.g. "en-US"
  supportedLanguageTags: string[] // e.g. ["en-US", "es-MX"]
}


// Raw response preserves the nested attributes structure
interface StorefrontRaw {
  id: string
  type: string
  href: string
  attributes: {
    explicitContentPolicy: string
    name: string
    defaultLanguageTag: string
    supportedLanguageTags: string[]
  }
}

```

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

### Define MusicKitResultWrapper

Source: https://musickit.js.org/reference/types

Generic wrapper used by all API methods to provide status, data, and error information.

```typescript
type MusicKitResultWrapper<T> = {
  status: number       // HTTP status code
  data: T              // Response payload
  error: string | null // Error message, or null on success
}
```

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

### Test Authentication Status

Source: https://musickit.js.org/getting-started

Verifies that the current credentials and token are valid by hitting the Apple Music API test endpoint.

```javascript
const status = await musicKit.testAuth()
// Returns 200 if the token is valid
```

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

### Define Album type

Source: https://musickit.js.org/reference/types

Represents an album entity including editorial notes and release details.

```typescript

type Album = {
  id: string
  artistName: string
  artwork: Artwork
  copyright: string
  editorialNotes: EditorialNotes
  genreNames: string[]
  isCompilation: boolean
  isComplete: boolean
  isMasteredForItunes: boolean
  isSingle: boolean
  name: string
  playParams: PlayParams
  recordLabel: string
  releaseDate: string
  trackCount: number
  upc: string
  url: string
  relationships: AlbumRelationships
}

```

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

### Define Song type

Source: https://musickit.js.org/reference/types

Represents a song entity with metadata, artwork, and relationship information.

```typescript

type Song = {
  id: string
  albumName: string
  artistName: string
  artwork: Artwork
  composerName: string
  discNumber: number
  durationInMillis: number
  genreNames: string[]
  hasLyrics: boolean
  isAppleDigitalMaster: boolean
  isrc: string
  name: string
  playParams: PlayParams
  previews: Preview[]
  releaseDate: string
  trackNumber: number
  url: string
  relationships: SongRelationships
}

```

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

### Define SearchResult

Source: https://musickit.js.org/reference/types

Structure for search results, containing pagination metadata and categorized resource arrays.

```typescript
interface SearchResult {
  nextOffset: number | null
  results: Partial<Record<SearchType, any[]>>
}
```

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

### Override Base URL

Source: https://musickit.js.org/getting-started

Configures a custom base URL for the client, useful for routing requests through proxies or local debugging servers.

```javascript
const musicKit = new MusicKit({ key: { id, teamId, p8 } })
musicKit.baseUrl = "http://localhost:8080/v1"
```

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

### Define Generic Relationship Types

Source: https://musickit.js.org/reference/types

Defines the structure for parsed and raw relationship data between resources.

```typescript
interface Datum {
  id: string
  type: string   // e.g. "songs", "albums", "artists"
  href: string
}


// Parsed: array of datums
type GenericRelationship = Datum[]


// Raw: object with href and nested data array
type GenericRelationshipRaw = {
  href: string
  data: Datum[]
}
```

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

### Define MusicVideo type

Source: https://musickit.js.org/reference/types

Represents a music video entity with technical specifications like 4K and HDR support.

```typescript

type MusicVideo = {
  id: string
  artistName: string
  artwork: Artwork
  durationInMillis: number
  genreNames: string[]
  has4K: boolean
  hasHDR: boolean
  isrc: string
  name: string
  playParams: PlayParams
  previews: Preview[]
  releaseDate: string
  url: string
  relationships: MusicVideoRelationships
}

```