Oh Dear JS SDK

This SDK lets you perform API calls to Oh Dear.

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

import OhDear from 'ohdear-js-sdk'

Authentication #

1. Get your api token from your ohdear app, Please, refer to this link for more information.
2. create new instance from OhDear and pass the api token via the constructor.

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:

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.

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

{
    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

{
    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

{
    code: 400,
    message: '...'
}

ValidationError

thrown when there's a validation error

{
    code: 422,
    message: '...'
    errors: [] // an array of errors
}

NotFoundError

thrown when site or check was not found

{
    code: 404,
    message: '...'
}

UnknownError

thrown when some unknown error happens

{
    code: 0,
    message: '...'
}

Credits

• Mohammed Manssour

License

The MIT License (MIT).