@syncfm/applemusic-api

Typed helpers around Apple Music catalog endpoints with shared configuration, logging, and token management. The client is still in active development, so expect method signatures to move as we close gaps.

Features

Zero configuration authentication with automatic scraping and validation of session tokens
Strong typing across endpoints for albums, artists, songs, music videos, search, hints, suggestions, and relationships
Consistent logging hooks so you can forward diagnostics to your own observability stack
Built with Bun and Vitest for fast builds and test feedback

Requirements

Node.js 18 or newer, or Bun 1.1 or newer
Optional developer or user tokens if you want to override the default scraped authentication flow

Guides, endpoint details, and configuration notes live at https://am-docs.syncfm.dev .

Installation

npm install @syncfm/applemusic-api
# or
pnpm add @syncfm/applemusic-api
# or
yarn add @syncfm/applemusic-api
# or
bun add @syncfm/applemusic-api

Quick start

import { AppleMusic, AuthType, Region } from "@syncfm/applemusic-api";

const music = new AppleMusic({
    region: Region.US,
    authType: AuthType.Scraped,
});

await music.init();

const results = await music.Search.search({
    term: "bad omens",
    types: ["songs", "albums"],
    limit: 5,
});

console.log(results.songs?.data?.map((song) => song.attributes?.name));

Endpoint usage examples

Every top level namespace mirrors an Apple Music resource. Each method enforces the correct parameter and response types.

await music.Albums.get({
    ids: ["1644355784"],
});

await music.Albums.getRelationship({
    id: "1644355784",
    relationship: "tracks",
});

await music.Suggestions.suggestions({
    term: "blind cha",
    limit: 10,
});

Configuration

AppleMusic accepts either an AppleMusicConfig instance or plain AppleMusicConfigParams.

region: defaults to Region.US but can be set to any supported storefront
authType: choose between Scraped, DeveloperToken, UserTokenViaDevToken, or UserTokenUnofficial
logger: pass a custom logger implementing the client logger interface, or configure the built in logger through loggerOptions

Tooling

Build: bun run build
Type check: bun run type-check
Tests with coverage: bun run test
Lint and format: bun run check
Generate reference docs: bun run docs:build

Documentation

Guides, endpoint details, and configuration notes live at https://am-docs.syncfm.dev .

Contributing

Fork the repository and create a feature branch
Install dependencies and run the test suite
Open a pull request with a clear description and examples

Please include tests or docs when you add new features.

Legal

Apple Music and the Apple logo are trademarks of Apple Inc., registered in the U.S. and other countries. This project is an independent community effort and is not affiliated with, endorsed by, or sponsored by Apple Inc. Any interaction with Apple services remains subject to Apple policies, terms, and applicable laws. Ensure you have the necessary authorization before using this client in your applications.

License

MIT License. See LICENSE.md for details.