feat: update to latest apple music api spec

src/AppleMusicAPI.ts

@@ -14,6 +14,7 @@ import { SearchManager } from './search/SearchManager';
 import { LibraryManager } from './library/LibraryManager';
 
 export class AppleMusicAPI {
+  _client: HttpClient;
   albums: CatalogManager<AlbumResponse>;
   artists: CatalogManager<ArtistResponse>;
   musicVideos: CatalogManager<MusicVideoResponse>;
@@ -27,18 +28,18 @@ export class AppleMusicAPI {
   };
 
   constructor(public configuration: Readonly<ClientConfiguration>) {
-    const client = new HttpClient(configuration);
+    this._client = new HttpClient(configuration);
 
-    this.albums = new CatalogManager<AlbumResponse>(client, 'albums');
-    this.artists = new CatalogManager<ArtistResponse>(client, 'artists');
-    this.musicVideos = new CatalogManager<MusicVideoResponse>(client, 'music-videos');
-    this.playlists = new CatalogManager<PlaylistResponse>(client, 'playlists');
-    this.songs = new CatalogManager<SongResponse>(client, 'songs');
-    this.stations = new CatalogManager<StationResponse>(client, 'stations');
-    this.search = new SearchManager<SearchResponse>(client);
+    this.albums = new CatalogManager<AlbumResponse>(this._client, 'albums');
+    this.artists = new CatalogManager<ArtistResponse>(this._client, 'artists');
+    this.musicVideos = new CatalogManager<MusicVideoResponse>(this._client, 'music-videos');
+    this.playlists = new CatalogManager<PlaylistResponse>(this._client, 'playlists');
+    this.songs = new CatalogManager<SongResponse>(this._client, 'songs');
+    this.stations = new CatalogManager<StationResponse>(this._client, 'stations');
+    this.search = new SearchManager<SearchResponse>(this._client);
     this.library = {
-      songs: new LibraryManager<SongResponse>(client, 'songs'),
-      playlists: new LibraryManager<PlaylistResponse>(client, 'playlists')
+      songs: new LibraryManager<SongResponse>(this._client, 'songs'),
+      playlists: new LibraryManager<PlaylistResponse>(this._client, 'playlists')
     };
   }
 }

src/interfaces/AppleMusic/album.ts

@@ -8,6 +8,8 @@ import { PlayParameters } from './playParameters';
 import { ArtistRelationship } from './artistRelationship';
 import { GenreRelationship } from './genreRelationship';
 import { TrackRelationship } from './trackRelationship';
+import { LibraryRelationship } from './libraryRelationship';
+import { RecordLabelRelationship } from './recordLabelRelationship';
 
 // https://developer.apple.com/documentation/applemusicapi/album
 export interface Album extends Resource {
@@ -21,27 +23,33 @@ namespace Album {
   export interface Attributes {
     albumName: string;
     artistName: string;
+    artistUrl?: string; // New field
     artwork?: Artwork;
-    contentRating?: ContentRating;
+    audioVariants?: string[]; // New field, with specific possible values
+    contentRating?: ContentRating; // Can now take string values like 'clean' or 'explicit'
     copyright?: string;
     editorialNotes?: EditorialNotes;
     genreNames: string[];
+    isCompilation: boolean; // New field
     isComplete: boolean;
+    isMasteredForItunes: boolean;
     isSingle: boolean;
     name: string;
     playParams?: PlayParameters;
     recordLabel: string;
-    releaseDate?: CalendarDate;
+    releaseDate?: string; // Updated to string
     trackCount: number;
-    url: string;
     upc?: string;
-    isMasteredForItunes: boolean;
+    url: string;
   }
+
 
   // https://developer.apple.com/documentation/applemusicapi/album/relationships
   export interface Relationships {
-    artists?: ArtistRelationship;
-    genres?: GenreRelationship;
-    tracks?: TrackRelationship;
-  }
+    artists?: ArtistRelationship; // The artists associated with the album (10 default, 10 max)
+    genres?: GenreRelationship; // The genres for the album, not included by default
+    tracks?: TrackRelationship; // The songs and music videos on the album (300 default, 300 max)
+    library?: LibraryRelationship; // New relationship: The album in the user’s library for the catalog album, if any
+    'record-labels'?: RecordLabelRelationship; // New relationship: The record labels for the album (10 default, 10 max)
+  }  
 }

src/interfaces/AppleMusic/artist.ts

@@ -5,6 +5,7 @@ import { GenreRelationship } from './genreRelationship';
 import { MusicVideoRelationship } from './musicVideoRelationship';
 import { PlaylistRelationship } from './playlistRelationship';
 import { StationRelationship } from './stationRelationship';
+import { Artwork } from './artwork';
 
 // https://developer.apple.com/documentation/applemusicapi/artist
 export interface Artist extends Resource {
@@ -16,18 +17,19 @@ export interface Artist extends Resource {
 namespace Artist {
   // https://developer.apple.com/documentation/applemusicapi/artist/attributes
   export interface Attributes {
+    artwork?: Artwork; // New field
     editorialNotes?: EditorialNotes;
     genreNames: string[];
     name: string;
     url: string;
   }
-
+  
   // https://developer.apple.com/documentation/applemusicapi/artist/relationships
   export interface Relationships {
-    albums?: AlbumRelationship;
-    genres?: GenreRelationship;
-    musicVideos?: MusicVideoRelationship;
-    playlists?: PlaylistRelationship;
-    station?: StationRelationship;
-  }
+    albums?: AlbumRelationship; // The albums associated with the artist (25 default, 100 max)
+    genres?: GenreRelationship; // The genres associated with the artist, not included by default
+    'music-videos'?: MusicVideoRelationship; // The music videos associated with the artist (25 default, 100 max)
+    playlists?: PlaylistRelationship; // The playlists associated with the artist (10 default, 10 max)
+    station?: StationRelationship; // The station associated with the artist, not included by default (one station)
+  }  
 }

src/interfaces/AppleMusic/artwork.ts

@@ -1,11 +1,11 @@
 // https://developer.apple.com/documentation/applemusicapi/artwork
 export interface Artwork {
-  bgColor?: string;
-  height: number;
-  width: number;
-  textColor1?: string;
-  textColor2?: string;
-  textColor3?: string;
-  textColor4?: string;
-  url: string;
+  bgColor?: string; // The average background color of the image
+  height: number; // Required: The maximum height available for the image
+  width: number; // Required: The maximum width available for the image
+  textColor1?: string; // The primary text color used if the background color is displayed
+  textColor2?: string; // The secondary text color used if the background color is displayed
+  textColor3?: string; // The tertiary text color used if the background color is displayed
+  textColor4?: string; // The final post-tertiary text color used if the background color is displayed
+  url: string; // Required: The URL to request the image asset. Must include {w}x{h} as placeholders for width and height.
 }

src/interfaces/AppleMusic/composerRelationship.ts

@@ -0,0 +1,6 @@
+import { Relationship } from './relationship';
+import { Artist } from './artist'; // Assuming composers are modeled like artists, you can change this if needed
+
+export interface ComposerRelationship extends Relationship {
+  data: Artist[]; // Assuming composers are part of the `Artist` interface, otherwise update this to the correct type
+}

src/interfaces/AppleMusic/curator.ts

@@ -13,10 +13,10 @@ export interface Curator extends Resource {
 namespace Curator {
   // https://developer.apple.com/documentation/applemusicapi/curator/attributes
   export interface Attributes {
-    artwork: Artwork;
-    editorialNotes?: EditorialNotes;
-    name: string;
-    url: string;
+    artwork: Artwork; // Required: The curator artwork
+    editorialNotes?: EditorialNotes; // Optional: The notes about the curator
+    name: string; // Required: The localized name of the curator
+    url: string; // Required: The URL for sharing the curator in Apple Music
   }
 
   // https://developer.apple.com/documentation/applemusicapi/curator/relationships

src/interfaces/AppleMusic/genre.ts

@@ -9,6 +9,9 @@ export interface Genre extends Resource {
 namespace Genre {
   // https://developer.apple.com/documentation/applemusicapi/genre/attributes
   export interface Attributes {
-    name: string;
-  }
+    name: string; // Required: The localized name of the genre
+    parentId?: string; // Optional: The identifier of the parent genre
+    parentName?: string; // Optional: The localized name of the parent genre
+    chartLabel?: string; // Optional: A localized string for displaying the genre in relation to charts
+  } 
 }

src/interfaces/AppleMusic/libraryRelationship.ts

@@ -0,0 +1,6 @@
+import { Relationship } from './relationship';
+import { Song } from './song'; // Assuming this refers to the library song, modeled like a song
+
+export interface LibraryRelationship extends Relationship {
+  data: Song[]; // Update to correct type if not a song
+}

src/interfaces/AppleMusic/musicVideo.ts

@@ -9,6 +9,8 @@ import { Preview } from './preview';
 import { AlbumRelationship } from './albumRelationship';
 import { ArtistRelationship } from './artistRelationship';
 import { GenreRelationship } from './genreRelationship';
+import { LibraryRelationship } from './libraryRelationship';
+import { SongRelationship } from './songRelationship';
 
 // https://developer.apple.com/documentation/applemusicapi/musicvideo
 export interface MusicVideo extends Resource {
@@ -21,28 +23,34 @@ namespace MusicVideo {
   // https://developer.apple.com/documentation/applemusicapi/musicvideo/attributes
   export interface Attributes {
     albumName?: string;
-    artistName: string;
-    artwork: Artwork;
-    contentRating?: ContentRating;
-    durationInMillis?: number;
+    artistName: string; // Required
+    artistUrl?: string; // New field
+    artwork: Artwork; // Required
+    contentRating?: ContentRating; // Can now take string values like 'clean' or 'explicit'
+    durationInMillis?: number; // Required
     editorialNotes?: EditorialNotes;
-    genreNames: string[];
-    isrc: string;
-    name: string;
+    genreNames: string[]; // Required
+    has4K: boolean; // Required
+    hasHDR: boolean; // Required
+    isrc: string; // Required
+    name: string; // Required
     playParams?: PlayParameters;
-    previews: Preview[];
-    releaseDate: CalendarDate;
+    previews: Preview[]; // Required
+    releaseDate: string; // Updated to string for YYYY-MM-DD or YYYY format
     trackNumber?: number;
-    url: string;
-    videoSubType?: string;
-    hasHDR: boolean;
-    has4K: boolean;
+    url: string; // Required
+    videoSubType?: string; // Updated with possible value 'preview'
+    workId?: string; // New field (for classical music)
+    workName?: string; // New field (for classical music)
   }
+
 
   // https://developer.apple.com/documentation/applemusicapi/musicvideo/relationships
   export interface Relationships {
-    albums?: AlbumRelationship;
-    artists?: ArtistRelationship;
-    genres?: GenreRelationship;
-  }
+    albums?: AlbumRelationship; // The albums associated with the music video (10 default, 10 max)
+    artists?: ArtistRelationship; // The artists associated with the music video (10 default, 10 max)
+    genres?: GenreRelationship; // The genres associated with the music video, not included by default
+    library?: LibraryRelationship; // The library for a music video if added to the library
+    songs?: SongRelationship; // The songs associated with the music video (10 default, 10 max)
+  }  
 }

src/interfaces/AppleMusic/musicVideoRelationship.ts

@@ -1,7 +1,6 @@
 import { Relationship } from './relationship';
-import { MusicVideo } from './musicVideo';
+import { MusicVideo } from './musicVideo'; // Use the existing MusicVideo interface
 
-// https://developer.apple.com/documentation/applemusicapi/musicvideorelationship
 export interface MusicVideoRelationship extends Relationship {
   data: MusicVideo[];
 }

src/interfaces/AppleMusic/playlist.ts

@@ -4,6 +4,7 @@ import { EditorialNotes } from './editorialNotes';
 import { PlayParameters } from './playParameters';
 import { CuratorRelationship } from './curatorRelationship';
 import { TrackRelationship } from './trackRelationship';
+import { LibraryRelationship } from './libraryRelationship';
 
 // https://developer.apple.com/documentation/applemusicapi/playlist
 export interface Playlist extends Resource {
@@ -16,18 +17,22 @@ namespace Playlist {
   // https://developer.apple.com/documentation/applemusicapi/playlist/attributes
   export interface Attributes {
     artwork?: Artwork;
-    curatorName?: string;
+    curatorName: string; // Required
     description?: EditorialNotes;
-    lastModifiedDate: Date;
-    name: string;
+    isChart: boolean; // New field, required
+    lastModifiedDate: string; // Updated to string for date format
+    name: string; // Required
     playParams?: PlayParameters;
-    playlistType: 'user-shared' | 'editorial' | 'external' | 'personal-mix';
-    url: string;
+    playlistType: 'user-shared' | 'editorial' | 'external' | 'personal-mix' | 'replay'; // Added 'replay'
+    url: string; // Required
+    trackTypes?: string[]; // New field, with possible values 'music-videos', 'songs'
   }
+
 
   // https://developer.apple.com/documentation/applemusicapi/playlist/relationships
   export interface Relationships {
-    curator?: CuratorRelationship;
-    tracks?: TrackRelationship;
+    curator?: CuratorRelationship; // The curator that created the playlist, includes identifiers only
+    library?: LibraryRelationship; // Library playlist for a catalog playlist if added to library
+    tracks?: TrackRelationship; // The songs and music videos included in the playlist (100 default, 300 max)
   }
 }

src/interfaces/AppleMusic/preview.ts

@@ -2,6 +2,7 @@ import { Artwork } from './artwork';
 
 // https://developer.apple.com/documentation/applemusicapi/preview
 export interface Preview {
-  artwork?: Artwork;
-  url: string;
+  artwork?: Artwork; // Optional: The preview artwork for the associated preview music video
+  url: string; // Required: The preview URL for the content
+  hlsUrl?: string; // Optional: The HLS preview URL for the content
 }

src/interfaces/AppleMusic/recordLabel.ts

@@ -0,0 +1,32 @@
+import { Artwork } from './artwork';
+import { Resource } from './resource';
+import { AlbumRelationship } from './albumRelationship'; // Assuming this is for releases related to the record label
+
+export interface RecordLabel extends Resource {
+  attributes?: RecordLabel.Attributes;
+  views?: RecordLabel.Views;
+  type: 'record-labels';
+}
+
+export namespace RecordLabel {
+  export interface Attributes {
+    artwork: Artwork; // Required: Artwork associated with the content
+    description?: string; // Optional: A map of description information (could be expanded if needed)
+    name: string; // Required: The (potentially) censored name of the content
+    url: string; // Required: The URL to load the record label from
+  }
+
+  export interface Views {
+    'latest-releases'?: RecordLabelLatestReleasesView; // New relationship for the latest releases
+    'top-releases'?: RecordLabelTopReleasesView; // New relationship for the top releases
+  }
+
+  // Define the Views for latest and top releases
+  export interface RecordLabelLatestReleasesView {
+    data: AlbumRelationship[]; // Assuming this points to albums (could change if it refers to something else)
+  }
+
+  export interface RecordLabelTopReleasesView {
+    data: AlbumRelationship[]; // Assuming this points to albums (could change if it refers to something else)
+  }
+}

src/interfaces/AppleMusic/recordLabelRelationship.ts

@@ -0,0 +1,6 @@
+import { Relationship } from './relationship';
+import { RecordLabel } from './recordLabel';
+
+export interface RecordLabelRelationship extends Relationship {
+  data: RecordLabel[];
+}

src/interfaces/AppleMusic/recordLabelResponse.ts

@@ -0,0 +1,5 @@
+import { RecordLabel } from './recordLabel';
+
+export interface RecordLabelResponse {
+  data: RecordLabel[]; // Required: The collection of record labels for the request
+}

src/interfaces/AppleMusic/searchResponse.ts

@@ -8,10 +8,16 @@ import { SongResponse } from './songResponse';
 // https://developer.apple.com/documentation/applemusicapi/searchresponse
 export interface SearchResponse extends ResponseRoot {
   results: {
-    songs: SongResponse;
-    albums: AlbumResponse;
-    playlists: PlaylistResponse;
-    artists: ArtistResponse;
-    'music-videos': MusicVideoResponse;
+    activities?: unknown; // You can define a specific type if needed
+    albums?: AlbumResponse;
+    'apple-curators'?: unknown; // You can define a specific type if needed
+    artists?: ArtistResponse;
+    curators?: unknown; // You can define a specific type if needed
+    'music-videos'?: MusicVideoResponse;
+    playlists?: PlaylistResponse;
+    'record-labels'?: unknown; // You can define a specific type if needed
+    songs?: SongResponse;
+    stations?: unknown; // You can define a specific type if needed
+    top?: unknown; // You can define a specific type if needed
   };
 }