@promise-watch/core

An Api/E2E monitor that runs promises on intervals and sends notifications on errors. Supports playwright for reliable E2E testing. Has prebuilt notifiers for SMTP, Slack, and Pushover, and can support any custom notifier.

Create a run directory where you write scripts, set options, then send notifications on errors. Checkout the example dir to see a working example.

./my-e2e-checks/
├── runs/
│   ├── checks-https-jasonraimondi-com.ts
│   └── checks-https-google-com.ts
├── promise-watch.config.ts
└── package.json

Your runs can be anything! It just needs to export an options: RunPageOptions and run: Promise<void>.

import { chromium } from "playwright";
import { RunPageOptions } from "@promise-watch/core";

export const options: RunPageOptions = {
  interval: 15,
};

export async function run() {
  const browser = await chromium.launch();
  const page = await browser.newPage();

  const response = await page.goto("https://jasonraimondi.com");

  if (response?.status && response.status() > 399) {
    throw new Error(`Failed with response code [${response.status()}].`);
  }

  await page.close({ runBeforeUnload: true });
  await browser.close();
}

Really, you can put anything in the promise.

export const options = {
  interval: 15,
};

export async function run() {
  // you can run anything here... if it throws an error, it will send a notification.
}

The default options:

type RunPageOptions = {
  interval: number; // required
  notifiers?: Notifier[]; // default: []
  logSuccess?: boolean; // default: false
  retryImmediatelyAfterFail?: boolean; // default: false
};

Getting Started

The best way to get started is to use the starter-template. Clone it down and then add your own custom runs to the runs/ directory.

Create a promise-watch.config.ts

You'll need to create your own config:

type PromiseWatchOptions = {
  globPath?: string; // defaults to "runs/**/*.{js,ts}"
  notifiers: Notifier[];
};

// promise-watch.config.ts

export default {
  notifiers: [],
}

Notifiers

Send notifications when errors occur using the following providers:

• ConsoleNotifier
• PushoverNotifier
• SlackNotifier
• SmtpNotifier

import { ConsoleNotifier } from "@promise-watch/core";

const options: ExecuteOptions = {
  ...,
  notifiers: [
    new ConsoleNotifier(),
    ...
  ]
}

Custom Notifiers

Implement the Notifier type and you're good to go. See the pushover notifier for a working example. Feel free to submit a PR if you want to add support for a custom notifier.

export type SendOptions = {
  title: string;
  body: string;
}

export type Notifier = {
  sendError(options: SendOptions): Promise<void>;
  sendRecovered(options: SendOptions): Promise<void>;
}

So you'd implement your own more or less like the following.

export class MyCustomNotifier implements Notifier {
  async sendError(options: SendOptions) {
    // handle custom error message
  }
  
  async sendRecovered(options: SendOptions) {
    // handle custom recovered message
  }
}

API Monitoring

Since it is just a Promise with errors being thrown, you can opt to just have a run that just makes an http api request to an endpoint. There is a helper package @promise-watch/axois that has a small helper for that.

import { checkHttp } from "@promise-watch/axios";

export const options = {
  interval: 30,
}

export async function run() {
  await checkHttp(new URL("https://jasonraimondi.com"));
}

Caveats

For now, this is not going scale to many runs nicely. I'm not sure the limit, but with enough runs, someone will surely find out for us!