# `@theorchard/backend-isni-api`

This is a client library for various ISNI APIs.

## Motivation

There is interest/requirements from DSP partners to support ISNI (International Standard Name Identifier) values to serve as a canonical reference to artists.

## Setup

Follow this [guide](https://www.notion.so/Javascript-Package-Management-Setup-9553d5d491c94835aa787fdf0fc4838d) to get your environment set up to work with private packages.

Then, add/install the package:

```sh
npm add @theorchard/backend-isni-api
```

## Usage

For the time being, this package only contains functionality related to the ISNI SRU search API. There are [many other](https://isni.org/page/technical-documentation/) ISNI APIs that require varying degrees of authorization which we may eventually need to integrate with. You can find more information about the Search SRU API in the [search subfolder README](src/search/README.md).

### `#search`

```ts
import { ISNISearchAPI } from "@theorchard/backend-isni-api";

const searchApi = new ISNISearchAPI();
console.log(await searchApi.search({ term: "Mitski" }));
```

```json
{
  "total": 1,
  "records": [
    {
      "isni": "458800553",
      "url": "https://isni.org/isni/0000000458800553",
      "confidence": 60,
      "name": "Mitski",
      "ids": {
        "musicBrainzId": "fa58cf24-0e44-421d-8519-8bf461dcfaa5"
      }
    }
  ],
  "request": {
    "query": "na%3D%22Mitski%22"
  }
}
```

### `#searchBestGuess`

```ts
import { ISNISearchAPI } from "@theorchard/backend-isni-api";

const searchApi = new ISNISearchAPI();
console.log(await searchApi.searchBestGuess({ term: "ABBA" }));
```

```json
{
  "isni": "109398682",
  "url": "https://isni.org/isni/0000000109398682",
  "confidence": 60,
  "name": "ABBA",
  "ids": {
    "musicBrainzId": "d87e52c5-bb8d-4da8-b941-9f4928627dc8"
  }
}
```

### `#byISNI`

```ts
import { ISNISearchAPI } from "@theorchard/backend-isni-api";

const searchApi = new ISNISearchAPI();
console.log(await searchApi.byISNI({ isni: "107225593" }));
```

```json
{
  "total": 1,
  "records": [
    {
      "isni": "107225593",
      "url": "https://isni.org/isni/0000000107225593",
      "confidence": 60,
      "name": "Beach House",
      "ids": {
        "musicBrainzId": "d5cc67b8-1cc4-453b-96e8-44487acdebea"
      }
    }
  ],
  "request": {
    "query": "isn%3D%22107225593%22"
  }
}
```

## Testing

```sh
pnpm test:unit
```

## Developing

```sh
awsume prod
```

Payloads returned from ISNI are stored in s3 buckets. You can run all of these through Zod schema validation by using the `validate` task:

```shell
$ pnpm validate

> @theorchard/backend-isni-api@0.0.4 validate /Users/bburton.ext/Workspace/backend-js-packages/packages/backend-isni-api
> tsx scripts/validate.ts

✔ Enter s3 bucket to check: … qa-isni-payloads
✅ 23 payloads in qa-isni-payloads were valid!
```

This will tell you if any of the payloads in the s3 bucket were invalid.