# @funkwhale/api

## Installation
```bash
yarn add @funkwhale/api
```

## Node usage
Node does not implement [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API). We need to polyfill it.
```ts
import { defaults, tracksList } from '@funkwhale/api'
import nodeFetch from 'node-fetch'

defaults.fetch = nodeFetch
defaults.baseUrl = 'https://funkwhale.instance.com/'

tracksList({ album: 1 }).then((response) => {
  console.log(response.data)
})
```

## Browser usage
```ts
import { defaults, tracksList } from '@funkwhale/api'

defaults.baseUrl = 'https://funkwhale.instance.com/'

tracksList({ album: 1 }).then((response) => {
  console.log(response.data)
})
```

## Vue 3 usage
```ts
// main.ts
import { createVueAPI } from '@funkwhale/api'
import { createApp } from 'vue'
import App from './App.vue'

const app = createApp(App)

app.install(createVueAPI({
  instanceUrl: 'https://funkwhale.instance.com/'
}))
```

```vue
// App.vue
<script setup>
import { tracksList } from '@funkwhale/api'
import { ref } from 'vue'

const count = ref(-1)

tracksList({ album: 1 }).then((response) => {
  count.value = response.data.count
})
</script>

<template>
  <div v-if="count > -1">
    Number of tracks in album:  {{ count }}
  </div>
  <div v-else>Fetching tracks...</div>
</template>
```

### Changing instance url
You can update the instance url manually by accessing the library store directly.
```ts
import { store } from '@funkwhale/api'

store.instanceUrl = 'https://another.funkwhale.instance.com/'
```

### Automatic instance url
The default instance url is set to [`window.location.origin`](https://developer.mozilla.org/en-US/docs/Web/API/Location/origin). If that's the case you're looking for, you can simply do:
```ts
// main.ts
import { createVueAPI } from '@funkwhale/api'

// ...

app.use(createVueAPI())
```

### Vuex managed instance url
If the instance url is managed by vuex, you can use `createVuexAPI` to add a mutation handler

::: warning
You should not update the instance url manually as described in [Changing instance url](#changing-instance-url). Vuex may override the set instance url. Instead please use Vuex mutations.
:::

::: danger
For the plugin to work properly, you mustn't update the instance url directly on the state. You must use mutations to change it!
:::

```ts
// store.ts
import { createVuexAPI } from '@funkwhale/api'

const store = createStore({
  // ...
  plugins: [
    createVuexAPI({
      stateKey: 'url', // key of the instance url in store state
      mutation: 'instance/setUrl' // mutation name
    }),
    // ...
  ]
})
```


## `@funkwhale/front` usage
The default options for `createVueAPI` and `createVuexAPI` are designed to work out of the box with `@funkwhale/front`.
```ts
// main.ts
import { createVueAPI } from '@funkwhale/api'

// ...

app.use(createVueAPI())
```

```ts
// store.ts
import { createVuexAPI } from '@funkwhale/api'

const store = createStore({
  // ...
  plugins: [
    createVuexAPI(),
    // ...
  ]
})
```