gbox-errors/readme.md

Error handlers

<h1 align="center">
	<img width="200" src="http://gauss.hr/wp-content/themes/olympos/images/landing/logo.svg" alt="gauss"> GaussBox Errors
</h1>

Build as support for Gauss Box API. Works with Sails.js only.

Build and format more readable error response for GaussBox.

## Install

```
$ npm install --save gbox-errors
```


## Config parameters

```
{
    "environment": "app environment",
    "packageJson": { content of package.json file}
    "emailConfig": {
        "host": "mail server host",
        "port": "mail server post",
        "user": "mail server username",
        "pass": "mail server password",
        "errorNotification": true,     // would be used for error notifications
        "contacts": ['mail.for.errors@mail.com'],
        "status": [500]     // for which http status codes mail would be sent
    },
    "sentry": {
        "configuration": {
            "dsn": "sentry dsn url"
        },
        "user": { user params for log outputs }
        "tags": { "tagKey": "tagValue", ... },
        "level": "error",
        "extra": { "key": "value", ... },
        "breadcrumb": {
            "message": "",
            "category": "",
            "level": ""
        }
    }

}
```
- **environment** - in production environment, error details would not be sent
- **packageJson** - this is used for detailed error output like apiName, version etc.
- **sentry** - this is used for sending error logs to sentry (only dsn is required, if some parameter is not set, then sentry defaults is used)
- **sentry.configuration** - this is sentry configuration options (dsn and environment is required, other is set only if provided)
- **sentry.user** - user details for filtering log outputs
- **sentry.tags** - tags for filtering log outputs
- **sentry.level** - you can set the severity of an event to one of five values: ‘fatal’, ‘error’, ‘warning’, ‘info’, and ‘debug’. (‘error’ is the default.) ‘fatal’ is the most severe and ‘debug’ is the least.
- **sentry.extra** - in addition to the structured context that Sentry understands, you can send arbitrary key/value pairs of data which will be stored alongside the event. These are not indexed and are simply used to add additional information about what might be happening
- **sentry.breadcrumb** - sentry breadcrumb options


## Usage in response


```
//Handle error in response
const formatError = require('gbox-errors')(config);

let error = formatError.format(data);

return this.res.status(error.status).json(error.response);

```

## Usage in controller

```
* optional

//status is number and message is string with min i char needed.
res.negotiate([status,message,options*])


//Example

res.negotiate([404,'Document id not found.']);

//Example with option

res.negotiate([404,'Document id not found.','Document Controller']);
```

## Handle GOT err response

```
//Example
return this.res.status(error.response.body.error.statusCode).json(error.response.body);
```

## Response

```
   * on error response data object is always empty
   * message object is for frontend and client

   //if sails run development mode, response extends with object error (see example)

    * apiTrace showing some info from package.json
    * errorTrace trace where error came from (if error can't be traced, errorTrace is removed)
```

```
//Example
//Production mode

{
    "data": [],
    "message": "Document fail"
}

//Example
//Development mode

{
    "data": [],
    "message": "Cannot read property 'body' of undefined",
    "error": {
        "statusCode": 500,
        "payload": {
            "statusCode": 500,
            "error": "Internal Server Error",
            "message": "Cannot read property 'body' of undefined"
        },
        "details": {
            "errorTrace": {
                "trace_1": {
                    "source": "at  (C:\\node_project\\Gbox v2\\erp\\documentApi\\api\\controllers\\document\\create.js:541:54)",
                    "lineNumber": 541,
                    "columnNumber": 54,
                    "fileName": "v2\\erp\\documentApi\\api\\controllers\\document\\create.js"
                }
            },
            "apiTrace": {
                "apiName": "document-api",
                "gboxErrorsVersion": "^2.2.3",
                "sqlVersion": "1.0.0",
                "sailsVersion": "1.0.2"
            },
            "generateBy": "gbox-errors ^2.2.3"
        },
        "validator": "5xx",
        "code": "UNHANDLED_ERROR",
        "enviroment": "development",
        "serverTime": "2018-9-18 13:33:16",
        "development": "TypeError: Cannot read property 'body' of undefined\n    at Object.sails.getDatastore.transaction [as during] (C:\\node_project\\Gbox v2\\erp\\documentApi\\api\\controllers\\document\\create.js:541:54)\n    at <anonymous>"
    }
}
```
## Helper

```
    /* if u need fast list */

    const notification = require('npm-gbErrors')();

    notification.errorList(); //Return list of available statuses
```

## Available status

```
    * 400 badRequest
    * 401 unauthorized
    * 402 paymentRequired
    * 403 forbidden
    * 404 notFound
    * 405 methodNotAllowed
    * 406 notAcceptable
    * 407 proxyAuthRequired
    * 408 clientTimeout
    * 409 conflict
    * 410 resourceGone
    * 411 lengthRequired
    * 412 preconditionFailed
    * 413 entityTooLarge
    * 414 uriTooLong
    * 415 unsupportedMediaType
    * 416 rangeNotSatisfiable
    * 417 expectationFailed
    * 422 badData
    * 423 locked
    * 424 failedDependency
    * 428 preconditionRequired
    * 429 tooManyRequests
    * 451 illegal
 ```


## Created by

[Dejan Kubaša,  Gauss d.o.o.](http://gauss.hr/)