Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/mohammedmanssour/ohdear-js-sdk

An SDK to easily work with the Oh Dear API
https://github.com/mohammedmanssour/ohdear-js-sdk

Last synced: 3 months ago
JSON representation

An SDK to easily work with the Oh Dear API

Awesome Lists containing this project

README 

        
# Oh Dear JS SDK



This SDK lets you perform API calls to [Oh Dear](https://ohdear.app/).



## Documentation



### List of contents

- Installation

- Authentication

- Sites

    - Get all sites in your account

    - Get site by id

    - Get site by url

    - Create new site

    - Delete a site

    - The `Site` Object

- Checks

    - Enabling a check

    - Disabling a check

    - Request a check run

- Uptime

    - Uptime Object

- Downtime

    - Downtime Object

- BrokenLinks

    - BrokenLink Object

- MixedContent

    - MixedContent Object

- Certificate Health

    - CertificateHealth Object

- Errors



### Installation #

Using npm:

```

npm install ohdear-js-sdk

```

and then import `OhDear` from `ohdear-js-sdk`

```js

import OhDear from 'ohdear-js-sdk'

```






### Authentication #

1. Get your **api token** from your ohdear app, Please, refer to [this link](https://ohdear.app/docs/api/authentication) for more information.

2. create new instance from `OhDear` and pass the **api token** via the constructor.

```js

const ohdear = new OhDear(token)

```






### Sites #

Get, create or delete site



#### Get all sites in your account #

`ohdear.sites(options)`: list all your sites in your account, This will return a promise that resolves with an array of `Site` or rejects with an error.



the `Site` # object has the following properties

```

id: ...

url: '...',

sortUrl: '...',

checks: [

    {

        id: ...,

        type: '...',

        label: '...',

        enabled: true|false

    }

]

```



The `options` object have the following structure:

``` js

options = {

    page: {

        size: 1,

        number: 200

    },

    sort: null,

    filter: {

        teamID: null

    }

}

```

You're allowd to use `sites` method without providing any parameters. To know more about the provided parameters, please refer to [this link](https://ohdear.app/swagger#/sites/get_sites).



#### Get site by id #

`ohdear.site(siteID)` : It will return a promise that resolves with `Site` object or rejects with an error.



#### Get site by url #

`ohdear.siteByUrl(url)` : It will return a promise that resolves with `Site` object or rejects with an error.



#### Create new site #

`ohdear.createSite(url, teamID)`: let's you add a site through SDK, `url` is the new site url while `teamID` is your team id. It will return a promise that resolves with `Site` object or rejects with an error.



#### Delete a site #

`ohdear.deleteSite(id)` where `id` is the site ID, It will return a promise that resolves with boolean or rejects with an error.






### Checks #

manage the Oh Dear! checks per site



#### Enabeling a check #

`ohdear.enableCheck(id)` where `id` is the check id, It will return a promise that resolves with boolean or rejects with an error.



#### Disabling a check #

`ohdear.disableCheck(id)` where `id` is the check id, It will return a promise that resolves with boolean or rejects with an error.



#### Request a check run #

If you want Oh Dear! to perform a specific check now, call the `requestRun(id)` method



`ohdear.requestRun(id)` where `id` is the check id, It will return a promise that resolves with boolean or rejects with an error.






### Uptime #

`ohdear.uptime(id, startedAt, endedAt, split='day')` lets you get uptime for site, The method expects four parameters

- `id`: site id.

- `startedAt`: a date in the form of `YmdHis` that determines the start of the range you want to get uptime for.

- `endedAt`: a date in the form of `YmdHis` that determines the start of the range you want to get uptime for.

- `split`: a string that determines how fine grained the answer periods should be. Valid values are `hour`, `day` and `month`.



It will return a promise that resolves with an array of `Uptime` objects or rejects with an error.



the `Uptime` # object has the following properties

```js

{

    datetime: '...',

    uptimePercentage: ...

}

```






### Downtime #

`ohdear.downtime(id: number, startedAt: string, endedAt: string)` lets you get downtime for site, The method expects three parameters

- `id`: site id.

- `startedAt`: a date in the form of `YmdHis` that determines the start of the range you want to get uptime for.

- `endedAt`: a date in the form of `YmdHis` that determines the start of the range you want to get uptime for.



It will return a promise that resolves with an array of `Downtime` objects or rejects with an error.



the `Downtime` # object has the following properties

```js

{

    startedAt: '...',

    endedAt: '...',

}

```






### Broken Links #

`ohdear.brokenLinks(id)` where `id` is the site id, lets you get list of broken links in the site. It will return a promise that resolves with and array of `BrokenLink` objects or rejects with an error.



the `BrokenLink` # object has the following properties

```

{

    statusCode: ...,

    crawledUrl: '...',

    foundOnUrl: '...'

}

```






### Mixed Content #

`ohdear.mixedContent(id)` where `id` is the site id, . It will return a promise that resolves with and array of `MixedContent` objects or rejects with an error.



the `MixedContent` # object has the following properties

```

{

    elementName: '...',

    mixedContentUrl: '...',

    foundOnUrl: '...'

}

```






### Certificate Health #

`ohdear.certificateHealth(id)` where `id` is the site id, . It will return a promise that resolves with and array of `CertificateHealth` objects or rejects with an error.



the `CertificateHealth` # object has the following properties

```

{

    //The details of the certificate that was found for the site.

    certificateDetails: {

        issuer: '...',

        valid_from: '...',

        valid_until: '...',

    } ,



    //An array of checks that were performed on the certificate

    certificateChecks: [

        {

            type: '...',

            label: '...'

            passed: '...'

        },

        ...

    ],



    //An array with all the issuer names in the chain of the certificate.

    certificateChainIssuers: ['...', '...']

}

```






### Errors #

All available methods will return a Promise that will reject with different types of errors when an error occurs, here's the list of available errors. All errors has a `code` property that identifies the error.



Here's a list of error with their properties



#### FailedActionError

thrown when method fails getting the data

```js

{

    code: 400,

    message: '...'

}

```



#### ValidationError

thrown when there's a validation error

```js

{

    code: 422,

    message: '...'

    errors: [] // an array of errors

}

```



#### NotFoundError

thrown when site or check was not found

```js

{

    code: 404,

    message: '...'

}

```



#### UnknownError

thrown when some unknown error happens

```js

{

    code: 0,

    message: '...'

}

```



## Credits

- [Mohammed Manssour](https://mohammedmanssour.me)



## License

The MIT License (MIT).