@syncfm/applemusic-api
A lil unofficial Type-Safe Apple Music client
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.
import { AppleMusic, Region, AuthType} from '@syncfm/applemusic-api';
async function main() { const appleMusic = new AppleMusic({ region: Region.US, authType: AuthType.Scraped });
await appleMusic.init();
const album = await appleMusic.Albums.get( { id: '310730204' } );
console.log(album.data[0]?.attributes?.name);}
main();
Early build, ready-to-use catalog toolkit
The Apple Music client already ships typed modules for Albums, Artists, Songs, Music Videos, Search, Suggestions, and Hints - all hanging off a single configuration that handles region, auth mode, structured logging, and token management. The lists below outline everything that's available in the current npm release.
Endpoints shipping now
Each endpoint class mirrors the Apple Music REST routes with typed params, responses, and helpers for includes, relationships, and pagination. Callers get compile-time feedback that matches the shapes emitted by the real API.
- Albums / Songs / Music Videos
- Methods map directly to REST routes and response objects. Use typed calls such as
get(),getView(), andgetRelationshipView()to retrieve resources, related collections, and relationship views with structured includes and paging helpers. - Artists
- Typed lookups and relationship helpers expose artist resources, discography, and related entities with compile-time checked include and query options.
- Search / Suggestions / Hints
- Search helpers offer typed query builders and return normalized result shapes for catalog search, suggestions, and hints.
Shared utilities
Supporting modules centralize configuration, authentication, and logging so endpoint code stays focused on Apple Music payloads.
- AppleMusicConfig
- Set region, authentication mode, and logger options at runtime, or swap them after initialization.
- Logger
- Structured logger with console and optional file destinations, plus custom sinks via configuration.
- Token storage
- TokenStorage persists Apple Music auth tokens, refreshes them transparently, and feeds the shared Axios clients.
- getAuthenticatedAxios()
- Exports the same authenticated Axios instance the client uses, for one-off calls or custom tooling.
Operational checkpoints
Guard rails for verifying connectivity, running CI, and documenting the current surface area while the library evolves.
- Client.init()
- Bootstraps shared Axios clients, configures authentication, and warms each endpoint prior to use.
- verifyTokenValidity()
- Executes a lightweight probe against Apple Music to confirm the configured token still works.
- Typedoc + Vitest
- Docs and tests live in the repo and regenerate during releases; Vitest suites cover endpoints, config, logging, and token helpers.
Roadmap
Items under active development. Follow progress in the repository issues and discussions.
- Playlists and library endpointsExtend the client with authenticated library helpers and playlist mutations.
- Configurable transport optionsSurface retry policies and caching hooks in
AppleMusicConfig. - User, Developer, and User (scraped) token flowsWire up more
AuthTypes to allow for user and developer token auth & authenticated / user-action requests. - More extensive docsPublish endpoint response shapes alongside examples in the guides.
Recent test run
Legal notice
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 Apple services accessed through this client remain subject to Apple policies and terms. Ensure you have appropriate authorization before using the API in your applications.