# Scoutnet Node.js API Client

This is an API client for the Scoutnet API developed and maintained by
[Scouternas e-tjänster](https://etjanster.scout.se/). It is automatically
generated from the
[Scoutnet OpenAPI document](https://github.com/Scouterna/scoutnet-api/blob/main/packages/scoutnet-openapi/schema/scoutnet.yaml).

The client uses [openapi-typescript](https://openapi-ts.dev/introduction) and
[openapi-fetch](https://openapi-ts.dev/openapi-fetch/) under the hood. This NPM
package exports all types generated by openapi-typescript as well as a modified
version of the `createClient` method from openapi-fetch. This means that you can
use just the types if you need to build something very custom. For complete
usage instructions, check out their documentation.

## Installation

The client is available on NPM:

```bash
npm i @scouterna/scoutnet
```

## Usage

### Creating the client

You must always start by creating an instance of the API client. This ensures
all requests will be fully type safe.

```ts
import { createClient } from '@scouterna/scoutnet'

const client = createClient();
```

You can pass options when creating the client that will apply to all requests.
For example, you might want to use a different server during development.

```ts
const client = createClient({
  baseUrl: 'https://s1.test.custard.no/api'
});
```

### Making requests

When making requests you provide the endpoint you want to call, and the types
are automatically inferred. Because all endpoints in the Scoutnet API have
unique access keys this is also where you set the Authorization header.

```ts
const result = await client.GET("/project/get/participants", {
  headers: {
    Authorization: createAuthorizationHeader({
      resourceId: '12345',
      key: '80vn4...n724',
    }),
  },
});

if (result.error) {
  // Handle the error properly
  throw new Error(`Request failed with status code ${result.response.status}`);
}

console.log(result.data.participants);
//                      ^ Access fully typed properties
```

Note that often times you will receive multiple levels of data and that when
those relations are empty, the API might return an empty array instead of an
object. Consider the following simplified example of a response:
```json
{
  "first_name": "Janne",
  "last_name": "Långben",
  "contact_info": {
    "1": "0701 23 45 67"
  }
}
```

As you can see the `contact_info` property contains an object of arbitrary data.
If instead there was no contact info the response would look like this:
```json
{
  "first_name": "Janne",
  "last_name": "Långben",
  "contact_info": []
}
```

Notice how `contact_info` suddenly became an empty array. This is a quirk of the
Scoutnet API that happens every time there is an empty object and you will have
to handle it accordingly. The return type of the API methods should help you
catch these cases.