npm package: @microtica/service-wrapper
Description: Service call library based on middleware-tester
Author: Microtica
Latest version: 1.0.0

# service
External service call library based on [middleware-tester](https://github.com/doxout/node-middleware-tester).
Mostly intended for JSON-based REST services.

## Usage
To instantiate a service:

```javascript
var Service = require("@microtica/service");

var myService = new Service("http://www.exampleservice.com");
// Let's get a reponse from http://www.exampleservice.com/test
myService.get("/test").then(function(response) {
    console.log("Response", response.body);
});
```

You can also try to make a subclass and wrap your calls:

```typescript
import Service = require("@microtica/service");

class MyService extends Service {
    constructor() { super("http://www.exampleservice.com"); }

    test() {
        return this.get("/test").then(Service.extractBody);
    }
}

const myService = new MyService();
myService.test().then(responseBody => {
    console.log("Response", responseBody);s
});
```

### Options
Requests can have additional options attached to them, either via parameter to each request or, if using your own subclass, overriding the `getDefaultOpt` function to apply the options to each request. The known options are:

* `query` - query string parameters.
* `doNotParseResponse` - if true, the service should not attempt to parse the incoming response as JSON.
* `ignoreStatusCode` - do not automatically throw an error if the status code is not one of the expected codes.

### Return values
All request calls are asynchronous. The JSON-based values return a response stream that also acts as a promise-like object. The following methods are available on the response stream:

* `then(succ, [err])` - works like a promise that resolves to the full response object, including `headers` and `statusCode`. Use `body` to get the parsed response body (if specified).
* `expect(codes)` - tells the request to regard the status codes specified by this method as success codes and throw an error if another code is received. Returns the same chainable object. Default values are `200` and `201`. To allow all status codes, use the `ignoreStatusCode` request option.
* `promise()` - returns a real promise version of the object.


## API
### constructor(baseUrl, [auth])
#### Params
* baseUrl - the base URL of the service. Has to be a valid http or https URL. Adding a port number is also supported.
* auth (optional) - if any authorization parameters are needed, you can set them up with this object. The object must have a `type` string parameter and a `credentials` object parameter that depends on the type. `type` can have one of the following values:
    * `"basic"` - basic HTTP authentication. Needs `username` and `password` credentials.
    * `"aws"` - AWS authentication. Requires: `secretAccessKey`, `region` and `accessKeyId`.
    * `"internal"` - requires `internalSecretHost`.

### getDefaultOpt([headers], [additionalOptions])
Override in a subclass to provide your own default options and headers for each request. By default, it will inject the `"X-Requested-With": "XMLHttpRequest"` header in every request.
Note that, even if not specified, requests with a body will have the `"Content-Length"` header set and JSON requests will have their `"Content-Type"` set to `"application/json"`. Additional auth headers may be added if the `auth` parameter is specified during construction.

Must return the default options.

### postForm(url, what, [headers])
POSTs a multipart/form to an URL. Returns the response stream.

### post(url, what, [headers], [additionalOptions])
POSTs an object as JSON to an URL. Will hang if nothing is posted.

### get(url, [qs], [headers], [additionalOptions])
GETs an URL, expecting a JSON response.

### delete(url, [qs], [headers], [additionalOptions])
DELETEs a resource at an URL, expecting a JSON response.

### options(url, [headers], [additionalOptions])
Makes an OPTIONS call to an URL.

### postRaw(url, [headers], [what])
Makes a POST request without any JSON conversion and returns a stream. Mostly intended for piping your request body into the request stream: e.g.
```javascript
var fs = require("fs");
var Service = require("@microtica/service");
var myService = new Service("http://www.exampleservice.com");
fs.createReadStream("myfile").pipe(myService.postRaw("/testfile"));
```

### getRaw(url, [qs])
Makes a GET request without any JSON conversion and returns a stream.

### getRequestOptions(opt)
Gets the request options object for a given request.

### extractBody(response)
Static convenience method that extracts the response body from the response object, mostly intended as a parameter for `then`, e.g.:
```javascript
return this.get("/test").then(Service.extractBody).then(function(responseBody) {
    console.log("This is the body only", responseBody);
});
```