# `music-artist-api-poc`

A proof of concept for interacting with the Apple Music for Artists API.

## Getting Started

This is a guide to using this library once it has been exported. If you would like to work on it locally, skip to the next section on getting started for dev.

First, import and instantiate `MusicArtistApi` from `@theorchard/something`:

```typescript
import { MusicArtistApi } from '@theorchard/something';

const api = new MusicArtistApi({
  keyId: process.env.KEY_ID,
  issuerId: process.env.ISSUER_ID,
  privateKeyPath: process.env.PRIVATE_KEY_PATH
});
```

### `#createArtist` "beta"

To create artists you must provide both a `name` and `primaryLocale`:

```typescript
import { CreateArtistResponse } from '@theorchard/something';

const result: CreateArtistResponse = await api.createArtist({
  name: "Gianni",
  primaryLocale: "es-ar",
});

console.log(result);

{
  "data": {
    "type": "musicContributors",
    "id": "578d578b-fde2-4619-bc64-a83eb8557fb8",
    "attributes": {
      "publicId": "578d578b-fde2-4619-bc64-a83eb8557fb8",
      "name": "Gianni",
    ...
```

The response payload for this example can be found in
[`createArtistPayloads`](./MusicArtistApi/__tests__/createArtistPayloads/)
directory under the UUID
[`578d578b-fde2-4619-bc64-a83eb8557fb8`](./MusicArtistApi/__tests__/createArtistPayloads/578d578b-fde2-4619-bc64-a83eb8557fb8-success.json). There are many payloads in this directory, and if you work on development of this library you will want to update them.

### `#getArtist` "alpha"

This retrieves an artist by either their Apple Music Artist API UUID:

```typescript
import { GetArtistResponse } from '@theorchard/something';

// for a UUID:
const result: GetArtistResponse = await api.getArtist({
  id: "578d578b-fde2-4619-bc64-a83eb8557fb8"
});

console.log(result);

{
  "data": {
    "type": "musicContributors",
    "id": "578d578b-fde2-4619-bc64-a83eb8557fb8",
    "attributes": {
      "publicId": "578d578b-fde2-4619-bc64-a83eb8557fb8",
      "name": "Gianni",
    ...
```

...or by an existing Apple Music public identifier:

```typescript
import { GetArtistResponse } from '@theorchard/something';

// for a legacy Apple ID:
const result: GetArtistResponse = await api.getArtist({
  id: "1457615237"
});

console.log(result);

{
  "data": {
    "type": "musicContributors",
    "id": "9534d82e-2eca-a358-3b47-7c78ea2d584f",
    "attributes": {
      "publicId": "9534d82e-2eca-a358-3b47-7c78ea2d584f",
      "name": "Myrna",
    ...
```

### `#searchArtist` WIP

Apple's documentation on this is incorrect, but a method has been implemented to their specification. Unfortunately it doesn't work and creating artists is the near term goal for this repository.

```typescript
await api.searchArtists({ query: "Atticus Ross" })

{
  "data": {
    ???
```

## Getting Dev Started

### Setup

Install [Deno](https://deno.com/). Set up the
[Deno VSCode LSP Extension](https://marketplace.visualstudio.com/items?itemName=denoland.vscode-deno).

Copy the `.env.shadow` file:

```shell
cp .env.shadow .env
```

Fill out the appropriate secrets (can be obtained from iTunes Connect via
DevOps).

The private key file should look like this:

```shell
cat privateKey.p8
-----BEGIN PRIVATE KEY-----
secretsecretsecretsecretsecretsecretsecretsecretsecretsecretsecr
etsecretsecretsecretsecretse
-----END PRIVATE KEY-----
```

The private key default filename is `privateKey.p8` which is `.gitignore`'d.

### Run the project

This is going to run`index.ts`, which has some typical use cases commented out in it.

```shell
deno task dev
```

## Project Details

The `createArtist` method of this library has been carefully crafted from only payloads that have been
approved by OPs to make valid production additions.

Apple doesn't really give QA environments for this sort of thing.

| Artist Name      | Primary Locale | Response Payload                                                                                             |
| ---------------- | -------------- | ------------------------------------------------------------------------------------------------------------ |
| Gianni           | es-ar          | [success](./MusicArtistApi/__tests__/createArtistPayloads/578d578b-fde2-4619-bc64-a83eb8557fb8-success.json) |
| Kevin The Bear   | en-gb          | [success](./MusicArtistApi/__tests__/createArtistPayloads/b6bb2754-bbb6-485d-a239-5d4981abb834-success.json) |
| Casi             | en-gb          | [success](./MusicArtistApi/__tests__/createArtistPayloads/350437ba-9ff2-4ac4-bf9f-6148e4546bdf-success.json) |
| ANNA MANU        | uk-uk          | [failure](./MusicArtistApi/__tests__/createArtistPayloads/2b9bb29c-8f81-4ace-85b5-5b6368a0f6d3-error.json)   |
| Your True Name   | en-us          | [success](./MusicArtistApi/__tests__/createArtistPayloads/e1ede4c2-0eac-4a70-b771-9acf6ea131f4-success.json) |
| 稲村 星          | ja-jp          | [success](./MusicArtistApi/__tests__/createArtistPayloads/7289134b-e7cc-4d35-a787-e11d690dda5f-success.json) |
| Father Wood      | en-us          | [success](./MusicArtistApi/__tests__/createArtistPayloads/49f78157-fc90-4601-9f6a-2344cd65d4b2-success.json) |
| Miss J           | en-us          | [success](./MusicArtistApi/__tests__/createArtistPayloads/c4936b40-fc3f-4d82-b2de-a6cf947543f1-success.json) |
| David Westen     | en-us          | [success](./MusicArtistApi/__tests__/createArtistPayloads/ceebc4df-8991-4051-b37d-39c14b7656f0-success.json) |
| UGLY             | en-us          | [success](./MusicArtistApi/__tests__/createArtistPayloads/97726d80-aa1c-4243-b1a8-3db00f469393-success.json) |
| Absolute Treat   | en-us          | [success](./MusicArtistApi/__tests__/createArtistPayloads/19fe2204-dcce-4da4-b4b9-ab05851f461d-success.json) |
| Næb / Dans & Lær | da-dk          | [success](./MusicArtistApi/__tests__/createartistPayloads/9cb5d929-1d29-4813-b486-b02cec0e5631-success.json) |

The filenames for the success payloads refer to the successfully created
`publicId` of the Artist, a UUID that Apple appears to be introducing alongside
`appleId`. If it's a failure, the UUID corresponds to the "error" payload's ID
field.