# Musicfetch

The type-safe JavaScript and TypeScript client for the
[Musicfetch API](https://musicfetch.io/docs). Resolve music-service URLs and
match tracks or albums by ISRC and UPC across Spotify, Apple Music, YouTube,
Deezer, TIDAL, and other supported services.

## Install

```sh
npm install musicfetch
```

```sh
yarn add musicfetch
```

## Create a client

```ts
import { Musicfetch } from 'musicfetch';

const musicfetch = new Musicfetch({
  token: process.env.MUSICFETCH_TOKEN!,
});
```

The client uses `https://api.musicfetch.io/` by default. You can provide a
different `endpoint` or a custom `fetch` implementation in the constructor.
Keep API tokens in server-side code and environment variables.

You can start a trial and create a token from
[Musicfetch pricing](https://musicfetch.io/#pricing).

## Look up a service URL

Use `url()` with a supported artist, album, or track URL:

```ts
const { result, errors } = await musicfetch.url({
  url: 'https://open.spotify.com/track/6habFhsOp2NvshLv26DqMb',
  services: ['appleMusic', 'deezer', 'youtube'],
});

if (result.type === 'track') {
  console.log(result.name);
  console.log(result.genres);
  console.log(result.services?.appleMusic?.link);
}
```

The result is a discriminated union with a `type` of `artist`, `album`, or
`track`.

## Look up a track by ISRC

```ts
const { result: track } = await musicfetch.isrc({
  isrc: 'USUG11901472',
  services: ['appleMusic', 'spotify', 'youtube'],
});

console.log(track.name);
console.log(track.services?.spotify?.link);
```

## Look up an album by UPC

```ts
const { result: album } = await musicfetch.upc({
  upc: '00602537618132',
  services: ['appleMusic', 'spotify', 'youtube'],
  withTracks: true,
});

console.log(album.name);
console.log(album.tracks);
```

## Open endpoint

`open()` calls the public Open URL endpoint. Its default return type is
`GetOpenUrlResult`, and a custom response type can be supplied when needed.

```ts
const { result } = await musicfetch.open({
  url: 'https://open.spotify.com/track/6habFhsOp2NvshLv26DqMb',
  services: ['appleMusic', 'youtube'],
  country: 'US',
});
```

## Lookup options

The lookup methods infer their return types from the requested options.
Common options include:

| Option | Description |
| --- | --- |
| `country` | Country or territory used for localized store links. Defaults to `US`. |
| `withAllLinks` | Return all localized links instead of only the requested country. |
| `withArtists` | Include related artists where supported. |
| `withAlbums` | Include related albums where supported. |
| `withTracks` | Include album tracks where supported. |
| `withLyrics` | Include track lyrics where supported. |
| `withCredits` | Include track or album credits where supported. |
| `withServiceLevel` | Include selected metadata inside each service result. |
| `fetchOptions` | Add request headers or framework-specific fetch options. |

For example, service-level fields are reflected in the inferred result:

```ts
const { result } = await musicfetch.isrc({
  isrc: 'USUG11901472',
  services: ['appleMusic', 'spotify'],
  withServiceLevel: ['isrc', 'genres', 'credits'],
});

console.log(result.services?.spotify?.isrc);
console.log(result.services?.appleMusic?.genres);
```

## Types and service helpers

The root package exports the client, lookup capability lists, and public result
types:

```ts
import {
  Musicfetch,
  SERVICES_WITH_SEARCH,
  SERVICES_WITH_URL_LOOKUP,
  type MusicfetchAlbum,
  type MusicfetchArtist,
  type MusicfetchItem,
  type MusicfetchLookupResult,
  type MusicfetchServiceType,
  type MusicfetchTrack,
} from 'musicfetch';
```

`SERVICES_WITH_URL_LOOKUP` contains services accepted as source URLs.
`SERVICES_WITH_SEARCH` contains services Musicfetch can search for matching
results.

## Brand assets

The `musicfetch/brands` export includes names, colors, URL patterns, and SVG
icons:

```ts
import brands from 'musicfetch/brands';

const spotify = brands.resolve('spotify');
const fromUrl = brands.resolve('https://open.spotify.com/track/...');

console.log(spotify?.name);
console.log(fromUrl?.color);
console.log(brands.all);
```

Brands can also be imported directly:

```ts
import spotify from 'musicfetch/brands/spotify';
import spotifyIconUrl from 'musicfetch/brands/spotify/icon.svg';
```

## React brand icons

Install React in your application, then render a bundled brand:

```tsx
import brands from 'musicfetch/brands';
import { BrandIcon } from 'musicfetch/react';

const spotify = brands.resolve('spotify');

export const SpotifyIcon = () =>
  spotify ? <BrandIcon brand={spotify} size={32} /> : null;
```

`BrandIcon` accepts `size`, `color`, `opacity`, `direction`, `className`,
`style`, and `testId`.

## Package exports

| Import | Contents |
| --- | --- |
| `musicfetch` | API client, capability lists, and public TypeScript types |
| `musicfetch/brands` | Brand collection and resolver |
| `musicfetch/brands/<service>` | A single brand definition |
| `musicfetch/brands/<service>/icon.svg` | A service SVG asset |
| `musicfetch/react` | React `BrandIcon` component |

See the complete [Musicfetch documentation](https://musicfetch.io/docs) for
endpoint behavior, supported parameters, and interactive examples.