npm package: @ovos-media/lib-director
Description: Utility package for the ope director service.
Latest version: 1.5.0

# Utilities for the OPE director

This module contains various utilities, helpers and components which allow you to communicate with the
OPE director and it's various services via a declarative interface.

### Installation

```bash
npm i -S @ovos-media/lib-director
```

### Usage

#### The ```DirectorClient(options)```

This package exports a ```DirectorClient``` class which can be used to easily interact with OPE services via a declarative interface.

```javascript
const client = new DirectorClient(options)
```
##### Options
- [string+mandatory] **consumerToken**: the public token which the director assigned for this consumer (see director dashboard)
- [string] **directorHost**: hostname (incl. protocol) of the director *(default: http://127.0.0.1)*
- [string] **directorPort**: port on which the director listens for requests *(default: 3001)*
- [string] **directorGraphQLPath**: director GraphQL endpoint *(default: "graphql")*
- [string] **directorRequestPath**: director endpoint which handles service requests *(default: "request")*

##### Public API

###### apolloClient

returns the apolloClient for this DirectorClient instance. This client is designed to handle the lib-directors "graphql" HOC parameters (service).

```javascript
<ApolloProvider client={myClient.apolloClient}>
  <MyApp />
</ApolloProvider>
```

For more information about the **graphql** HOC, see below.

###### consumer()

returns the consumer data for the consumer token with which this client is currently connected.

```javascript
import client from './myDirectorClient';

console.log(client.consumer());
```

This will log:
```json
{
  "id":"57ee1b72ba73513c489ea5ca",
  "name":"Director Dashboard",
  "slug":"director-dashboard",
  "services":[
    {
      "service": {
        "id":"57e525111f865a255856d72f",
        "name":"Localization",
        "slug":"localization"
      },
      "read":true,
      "write":false,
      "reqUserToken":true
    }
  ]
}
```

##### fetch('serviceSlug', 'servicePath', options)
The ```fetch``` function can be used to call any API / Endpoint of an OPE service without the need to setup all the headers manually.

It is a wrapper around the native (or polyfilled) ```fetch``` function and will automatically handle X-OPE-* headers and also take care of status codes (200 - 300 resolve, all other reject).

This function returns a ```Promise```.

```javascript
client.fetch(
  'oauth',
  'oauth/token',
  {
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded'
    },
    body: `grant_type=password&username=max&password=muster`
  }
)
.then((res) => res.json())
.then((res) => { console.log(res); })
```

For services / paths where you have configured the "Require User" checkbox, you can add the option "authorize:true" and lib-director is going to attach the correct authorization header.

```javascript
client.fetch('hello-world', 'test', { authorize: true });
```

#### Higher Order Components

##### ```graphql(service, query, options)```

This HOC is a wrapper for apollo-react's own ```graphql``` HOC.

It allows you to *pass in the slug of the service to which this query should be sent* and will automatically add all necessary headers to the network request so director will be able to validate, authorize and forward the request.

This way, you don't have to worry about setting X-OPE-Token, X-OPE-Service, X-OPE-Service-Path or an Authorization header (if the consumer-service connection requires one).

```javascript
import { graphql, gql } from '@ovos-media/lib-director';

const GET_DATASETS = gql`
  query datasets {
    datasets {
      id, name
    }
  }
`

const ConnectedComponent = graphql(
  'localization', // service slug
  GET_DATASETS, // graphql query
  {
    options: {
      forceFetch: true
    }
  }
)(Component);

export default ConnectedComponent;
```