perry: A TypeScript repository from Perry.js

Perry is a spy. His job is to help finding bugs in your application.

Summary

Description
Getting Started
- Using a CDN
- Using NPM
API
Options
Contributing
- Getting started
- Pull Requests
Collaborators
License

Description

Perry.js is an Agnostic Bug Reporter tool that you can just plug in any website.

It allows you to record bug reports in web applications regardless of how they're built. It supports a programmatic API but also comes with a Preact Widget that can be loaded on the fly (thanks to Webpack Code Splitting).

You can learn more about it's capabilities at https://perry-js.netlify.com/

Perry.js is still in active development and can be experimented in internal environments.

We still do not recommend Perry for log transporting, but we do recommend giving it a try for QA bug reporting.

You can find some implementation examples in these repo's:

React (using CDN): https://github.com/perry-js/perry-react-cdn-example
Vanilla (using CDN): https://github.com/perry-js/perry-vanilla-parcel-example
Vue (using CDN): https://github.com/perry-js/perry-vue-cdn-example

More examples are being built currently too.

You can track these implementations here: #52

Getting started

Using a CDN

Disclaimer: We still didn't deployed Perry into a CDN.

Meanwhile, you can experiment using the current netlify build.

<script src="https://perry-js.netlify.com/bundle.js"></script>
<script>
  /* This is an example plugin for handling perry's report */
  function ConsoleLogPlugin(reportInfo) {
    console.log("[Perry Report Info]:", reportInfo);
    console.log("[Perry Report Info]:", [
      "",
      "This was printed by the ConsoleLogPlugin.",
      "It is implemented inline into this test page.",
      "To know more about how to implement a Perry Plugin:",
      "Checkout this page src code or the github repository."
    ].join("\n"));

    alert([
      "[Perry Report Info]: Please check your console logs to see the recording report.",
      "Sorry for the alert as well, we'll get rid of it soon! <3"
    ].join("\n"));
  }

  /* Initialize Perry.js */
  const perry = new window.Perry({
    /* Enables log recording */
    log: true,
    /* Enables click recording */
    clicks: true,
    /* Enables screen recording */
    enableScreenRecording: true,
    /* Plugins are ways to handle the bug reporting submission */
    plugins: [ConsoleLogPlugin]
  });

  (async () => {
    /* Starts Perry Recorder */
    await perry.start();

    /* Stops Perry Recorder */
    await perry.stop();

    /* Submit's Perry Report */
    await perry.submit({
      title: 'test-report',
      description: 'A test report'
    });

    /* You can aso render Perry Widget for UI Control */
    await perry.render();
  })();
</script>

Using NPM

Disclaimer: We still didn't deployed Perry into NPM properly.

This documentation is stated here as a demonstration of how it will look like.

Installation

npm install --save perryjs

Usage

import Perry from 'perryjs';

/* This is an example plugin for handling perry's report */
function ConsoleLogPlugin(reportInfo) {
  console.log("[Perry Report Info]:", reportInfo);
  console.log("[Perry Report Info]:", [
    "",
    "This was printed by the ConsoleLogPlugin.",
    "It is implemented inline into this test page.",
    "To know more about how to implement a Perry Plugin:",
    "Checkout this page src code or the github repository."
  ].join("\n"));

  alert([
    "[Perry Report Info]: Please check your console logs to see the recording report.",
    "Sorry for the alert as well, we'll get rid of it soon! <3"
  ].join("\n"));
}

/* Initialize Perry.js */
const perry = new Perry({
  /* Enables log recording */
  log: true,
  /* Enables click recording */
  clicks: true,
  /* Enables screen recording */
  enableScreenRecording: true,
  /* Plugins are ways to handle the bug reporting submission */
  plugins: [ConsoleLogPlugin]
});

(async () => {
  /* Starts Perry Recorder */
  await perry.start();

  /* Stops Perry Recorder */
  await perry.stop();

  /* Submit's Perry Report */
  await perry.submit({
    title: 'test-report',
    description: 'A test report'
  });

  /* You can aso render Perry Widget for UI Control */
  await perry.render();
})();

API

Method	Signature	Description
`constructor`	`new Perry(options: PerryOptions): Perry`	Returns an instance of Perry.
`notify`	`perry.notify(error: Error): Promise<void>`	A programatic API so you can let perry know of errors without it having to catch them. Useful when handling errors.
`render`	`perry.render(): Promise<void>`	Fetches the Perry Widget component, appends a `#perry-widget` element into the document body and renders Perry Widget inside of it.
`start`	`perry.start(): Promise<void>`	Tries to start the perry watcher. If something goes wrong, it will stop it and throw an error.
`stop`	`perry.stop(): Promise<void>`	Stops the perry watcher.
`submit`	`perry.submit(reportInfo: IPerryReportInfo): Promise<IPerryReport>`	Aggregates the whole reporting session into the structure defined in the `IPerryReport` interface, invokes all plugins giving it as an argument and then returns it. Resolves after executing all the plugins configured.

Options

Option	Description	Type	Default
`log`	Enables `console.log()` calls to be monitored	`boolean`	`false`
`warn`	Enabled `console.warn()` calls to be monitored	`boolean`	`true`
`error`	Enabled `console.error()` calls to be monitored	`boolean`	`true`
`clicks`	Enables a listener on `document.onclick` with screen and viewport information	`boolean`	`false`
`cookies`	Returns the customer browser cookies in the final report	`boolean`	`false`
`localStorage (WIP)`	Returns `localStorage` data in the final report	`boolean`	`false`
`sessionStorage (WIP)`	Returns `sessionStorage` data in the final report	`boolean`	`false`
`clearOnReload`	Will clear the perry store everytime you reload it's instance	`boolean`	`false`
`clearOnStart`	Will clear the perry store everytime you start a bug reporting session	`boolean`	`true`
`ignoreScriptErrors`	Ignore's external script error messages.	`boolean`	`false`
`enableScreenRecording`	Enables Screen Recording through the MediaDevices and MediaRecorder API's.	`boolean`	`true`
`plugins`	Allows you to inject handlers for the reports generated by Perry. (e.g.: You can send data to your API using it).	`ReadonlyArray<(reportInfo: PerryReportInfo) => void>`	`[]`

perry-js/perry