From 95338f676ee86e4b724c5f8a48431eb8d05925a4 Mon Sep 17 00:00:00 2001
From: Janis Hutz <development@janishutz.com>
Date: Sat, 29 Aug 2026 15:17:10 +0200
Subject: [PATCH] feat: improved types, changes coming

---
 MusicKit.d.ts         | 13 +++++--
 MusicKitAPI.d.ts      | 15 ++++++++
 MusicKitInstance.d.ts | 79 ++++++++++++++++++++++++++++++++++++++++++-
 enums.d.ts            | 11 ++++++
 index.d.ts            |  4 +++
 package.json          | 23 +++++++++++++
 6 files changed, 142 insertions(+), 3 deletions(-)
 create mode 100644 MusicKitAPI.d.ts

diff --git a/MusicKit.d.ts b/MusicKit.d.ts
index 5d4387a..e91dae5 100644
--- a/MusicKit.d.ts
+++ b/MusicKit.d.ts
@@ -1,5 +1,10 @@
+/* eslint-disable @typescript-eslint/triple-slash-reference */
+/// <reference path="MusicKitInstance.d.ts" />
+/// <reference path="enums.d.ts" />
+/// <reference path="MusicKitAPI.d.ts" />
+
 declare namespace MusicKit {
-    interface MusicKitConfiguration {
+    export interface MusicKitConfiguration {
         /**
          * See https://js-cdn.music.apple.com/musickit/v3/docs/iframe.html?path=/story/get-started--page#configuring-musickit-on-the-web
          */
@@ -34,5 +39,9 @@ declare namespace MusicKit {
         'storefrontId'?: string;
     }
 
-    function configure ( config: MusicKitConfiguration ): Promise<MusicKitInstance>;
+    export function configure ( config: MusicKitConfiguration ): Promise<MusicKitInstance>;
+
+    export function getInstance (): MusicKitInstance;
+
+    export function formatArtworkURL ( artwork: Artwork, width: number, height: number ): string;
 }
diff --git a/MusicKitAPI.d.ts b/MusicKitAPI.d.ts
new file mode 100644
index 0000000..3a20eb2
--- /dev/null
+++ b/MusicKitAPI.d.ts
@@ -0,0 +1,15 @@
+declare namespace MusicKit {
+    interface MusicKitAPI {
+        'music': (
+            path: string,
+            params: {
+                [key: string]: string
+            },
+            opts: {
+                'fetchOptions': RequestInit
+            }
+        ) => Promise<{
+            'data': unknown
+        }>
+    }
+}
diff --git a/MusicKitInstance.d.ts b/MusicKitInstance.d.ts
index a8642bc..c8792fb 100644
--- a/MusicKitInstance.d.ts
+++ b/MusicKitInstance.d.ts
@@ -1,3 +1,80 @@
 declare namespace MusicKit {
-    interface MusicKitInstance {}
+    type MediaItem = object;
+
+    interface Queue {
+        'currentItem': MediaItem;
+        'isEmpty': boolean;
+        'items': MediaItem[];
+        'length': number;
+        'nextPlayableItem': MediaItem;
+        'position': number;
+        'previousPlayableItem': MediaItem;
+    }
+
+    interface QueueOptions {
+        'album'?: string;
+        'albums'?: string[];
+        'musicVideo'?: string;
+        'musicVideos'?: string[];
+        'playlist'?: string;
+        'playlists'?: string[];
+        'song'?: string;
+        'songs'?: string[];
+    }
+
+    interface SeekSeconds {
+        'BACK': number;
+        'FORWARD': number;
+    }
+
+    interface MusicKitInstance {
+        'api': Readonly<MusicKitAPI>;
+        'bitrate': Readonly<PlaybackBitrate>;
+        'currentPlaybackDuration': Readonly<number>;
+        'currentPlaybackProgress': Readonly<number>;
+        'currentPlaybackTime': Readonly<number>;
+        'currentPlaybackTimeRemaining': Readonly<number>;
+        'isAuthorized': Readonly<boolean>;
+        'isPlaying': Readonly<boolean>;
+        'nowPlayingItem': Readonly<MediaItem>;
+        'nowPlayingItemIndex': Readonly<number>;
+        'playbackRate': Readonly<number>;
+        'playbackState': Readonly<PlaybackStates>;
+        'previewOnly': Readonly<boolean>;
+        'queue': Readonly<Queue>;
+        'queueIsEmpty': Readonly<boolean>;
+        'repeatMode': Readonly<PlayerRepeatMode>;
+        'seekSeconds': Readonly<SeekSeconds | undefined>;
+        'shuffleMode': Readonly<PlayerShuffleMode>;
+        'storefrontCountryCode': Readonly<string>;
+        'storefrontId': Readonly<string>;
+        'videoContainerElement': Readonly<HTMLVideoElement | undefined>;
+        'volume': Readonly<number>;
+        'addEventListener': ( name: string, callback: CallableFunction, options: {
+            'once': boolean
+        } ) => void;
+        'authorize': () => Promise<string | void>;
+        'changeToMediaAtIndex': ( index: number ) => Promise<void>;
+        'changeToMediaItem': ( descriptor: MediaItem | string ) => Promise<void>;
+        'changeUserStorefront': ( storefrontId: string ) => Promise<void>;
+        'clearQueue': () => Promise<Queue>;
+        'exitFullscreen': () => void;
+        'mute': () => void;
+        'pause': () => void;
+        'play': () => void;
+        'playAt': ( position: number, options: QueueOptions ) => Promise<Queue | void>;
+        'playLater': ( options: QueueOptions ) => Promise<Queue | void>;
+        'playNext': ( options: QueueOptions, clear: boolean ) => Promise<Queue | void>;
+        'removeEventListener': ( name: string, callback: CallableFunction ) => void;
+        'requestFullscreen': () => void;
+        'seekBackward': () => Promise<void>;
+        'seekForward': () => Promise<void>;
+        'seekToTime': ( time: number ) => Promise<void>;
+        'setQueue': ( options: QueueOptions ) => Promise<Queue | void>;
+        'skipToNextItem': () => Promise<void>;
+        'skipToPreviousItem': () => Promise<void>;
+        'stop': () => void;
+        'unauthorize': () => Promise<void>;
+        'unmute': () => void;
+    }
 }
diff --git a/enums.d.ts b/enums.d.ts
index 50126f3..35f04c5 100644
--- a/enums.d.ts
+++ b/enums.d.ts
@@ -33,4 +33,15 @@ declare namespace MusicKit {
         'on',
         'off'
     }
+
+    interface Artwork {
+        'bgColor': string;
+        'height': number;
+        'width': number;
+        'textColor1': string;
+        'textColor2': string;
+        'textColor3': string;
+        'textColor4': string;
+        'url': string;
+    }
 }
diff --git a/index.d.ts b/index.d.ts
index e69de29..a4d70cc 100644
--- a/index.d.ts
+++ b/index.d.ts
@@ -0,0 +1,4 @@
+/* eslint-disable @typescript-eslint/triple-slash-reference */
+/// <reference path="MusicKit.d.ts">
+
+declare var MusicKit: MusicKit;
diff --git a/package.json b/package.json
index a5b8ec0..0da491f 100644
--- a/package.json
+++ b/package.json
@@ -1,4 +1,27 @@
 {
+  "name": "musickitjs-v3-types",
+  "version": "1.0.0",
+  "description": "Types for musickit js version 3.0",
+  "keywords": [
+    "musickitjs",
+    "types"
+  ],
+  "homepage": "https://github.com/janishutz/musickitjs-v3-types#readme",
+  "bugs": {
+    "url": "https://github.com/janishutz/musickitjs-v3-types/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/janishutz/musickitjs-v3-types.git"
+  },
+  "license": "GPL-3.0-or-later",
+  "author": "Janis Hutz",
+  "type": "module",
+  "main": "index.js",
+  "types": "./index.d.ts",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "@stylistic/eslint-plugin": "^5.10.0",