node-musickit-api

A TypeScript wrapper for the Apple Music API for Node.js. Fully typed, promise-based, and ready for production.

v3 is a complete rewrite. Nothing is shared with previous versions — API, types, and internals are all new. If you're migrating from v2, treat this as a new package.

Requirements

You must be enrolled in the paid Apple Developer Program ($99/yr) and have created a key with MusicKit privileges.

Installation

npm install node-musickit-api
# or
yarn add node-musickit-api
# or
bun add node-musickit-api

Quick Start

import { MusicKit } from "node-musickit-api";

const musicKit = new MusicKit({
  key: {
    id: "YOUR_KEY_ID",
    teamId: "YOUR_TEAM_ID",
    p8: process.env.MUSICKIT_P8!, // Full content of the .p8 key
  },
});

// Authenticate (generates a JWT developer token valid for 180d)
await musicKit.auth();

// Fetch a song by its Apple Music catalog ID
const song = await musicKit.songs.get("us", "1893742010");
console.log(song.data);

Security note: Never hardcode your private key (p8) in source code. Always load it from environment variables (e.g. process.env.MUSICKIT_P8) or a secrets manager. The example above uses MUSICKIT_P8 - set it in a .env file or your deployment environment.

API

auth()

Generates and caches a JWT developer token from your MusicKit key. Must be called before any other request.

testAuth()

Validates your developer token against the Apple Music API. Returns the HTTP status code.

Resources

Every resource method returns MusicKitResultWrapper<T>:

{
  status: number;     // HTTP status code
  data: T | null;     // response data (null on error)
  error: string | null; // error body (null on success)
}

All get* methods accept an optional raw parameter:

• raw: true → returns the unflattened API response
• raw: false (default) → returns a flattened/parsed response with cleaned-up attributes and relationships

Songs

Method	Description
get(storefront, id, raw?)	Fetch a song by catalog ID
getByISRC(storefront, isrc, raw?)	Fetch songs by ISRC code

Albums

Method	Description
get(storefront, id, raw?)	Fetch an album by catalog ID
getByUPC(storefront, upc, raw?)	Fetch albums by UPC code

Artists

Method	Description
get(storefront, id, raw?)	Fetch an artist by catalog ID

Music Videos

Method	Description
get(storefront, id, raw?)	Fetch a music video by catalog ID
getByISRC(storefront, isrc, raw?)	Fetch music videos by ISRC code

Storefronts

Method	Description
getAll(props?, raw?)	List all storefronts (limit, offset supported)
get(storefront, props?, raw?)	Fetch a single storefront (l, include, extend supported)

Search

search(storefront, params, raw?): Promise<MusicKitResultWrapper<SearchResult>>

SearchParams:

Param	Type	Description
term	string	Search query
types	SearchType[]	Resource types to search (e.g. "songs", "albums", "artists")
l	string	Language tag (optional)
limit	number (1–25)	Results per type (optional)
offset	number	Pagination offset (optional)
with	string[]	Additional resources to include (optional)

Usage:

const results = await musicKit.search("us", {
  term: "Tame Impala",
  types: ["songs", "albums"],
  limit: 5,
});

console.log(results.data.results.songs);

Documentation

Full API reference is available at musickit.js.org.

License

MIT