@rapidrest/core 1.0.1

package/dist/types/ClassLoader.d.ts

@@ -0,0 +1,87 @@
+/**
+ * The *ClassLoader* provides a container for dynamically loading classes at runtime using C#/Java style namespaces.
+ * Namespaces are determined from the folder structure relative to the root.
+ *
+ * Class names are derived either directly from the modules export name or inferred from the module's file path when
+ * the `default` export is used.
+ *
+ * For example, given the following example TypeScript module at relative path `com/company/MyClass.ts` would register
+ * a class with fully qualified name `com.company.MyClass`.
+ *
+ * ```javascript
+ * export default class MyClass {
+ *     // ...
+ * }
+ * ```
+ *
+ * In the event that multiple exports are defined, the fully qualified name will take on the export name instead of the
+ * module name. Thus, the following example module at relative path `com/company/MyClasses.ts` would register the following
+ * classes.
+ * - `com.company.MyClass`
+ * - `com.company.MyEnum`
+ *
+ * ```javascript
+ * export class MyClass {
+ *     // ...
+ * }
+ *
+ * export enum MyEnum {
+ *     // ...
+ * }
+ * ```
+ *
+ * **IMPORTANT**: If you use *ClassLoader* to dynamically load TypeScript files (.ts, .cts, .mts, etc.) at runtime using
+ * an ESM-only project you must use the `ts-node/esm` module loader. This can be specified by passing the `--loader` to
+ * node at runtime.
+ *
+ * ```
+ * node --loader ts-node/esm <module>
+ * ```
+ *
+ * @author Jean-Philippe Steinmetz
+ */
+export declare class ClassLoader {
+    /** The map containnig all loaded classes. */
+    protected classes: Map<string, any>;
+    protected ignore: (string | RegExp)[];
+    /** Indicates if TypeScript classes should be loaded. */
+    protected includeTypeScript: boolean;
+    /** Indicates if JavaScript classes should be loaded. */
+    protected includeJavaScript: boolean;
+    /** The path to the root directory containing all classes on disk. */
+    protected rootDir: string;
+    /**
+     * Creates a new instance of `ClassLoader` with the specified defaults.
+     *
+     * @param rootDir The root directory to load all classes from.
+     * @param includeJavaScript Set to `true` to load all TypeScript classes from the given `rootDir`, otherwise set to `false.
+     * @param includeTypeScript Set to `true` to load all JavaScript classes from the given `rootDir`, otherwise set to `false.
+     * @param ignore A list of regex pattern of file paths to ignore.
+     */
+    constructor(rootDir: string, includeJavaScript?: boolean, includeTypeScript?: boolean, ignore?: (string | RegExp)[]);
+    /**
+     * Returns the class with the specified fully qualified name.
+     *
+     * @param fqn The fully qualified name of the class to return.
+     * @returns The class definition for the given fully qualified name if found, otherwise `undefined`.
+     */
+    getClass(fqn: string): any | undefined;
+    /**
+     * Returns the map containing all classes that have been loaded.
+     */
+    getClasses(): Map<string, any>;
+    /**
+     * Returns `true` if a class exists with the specified fully qualified name.
+     *
+     * @param fqn The fully qualified name of the class to search.
+     * @returns `true` if a class definition exists for the given fully qualified name, otherwise `false`.
+     */
+    hasClass(fqn: string): any | undefined;
+    /**
+     * Loads all modules exports contained in the directory specified. The folder must be a child
+     * directory to the `rootDir` parameter passed in to the constructor.
+     *
+     * @param dir The directory, relative to `rootDir`, containing modules to load.
+     */
+    load(dir?: string): Promise<void>;
+}

package/dist/types/FileUtils.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Utility functions for working with files.
+ * @author Jean-Philippe Steinmetz
+ */
+export declare class FileUtils {
+    /**
+     * Attempts to write the provided contents to the file path given. If a file already exists the user is prompted to
+     * allow the file to be overwritten or merged. In the case of a merge, srcPath is used as a baseline in order to
+     * perform a 3-way merge.
+     *
+     * @param {string} srcPath The baseline template file to use during a merge.
+     * @param {string} outPath The destination file path to be written.
+     * @param {any} contents The contents of the file to write.
+     * @param {boolean} overwrite Set to `true` to overwite the file and not perform a merge.
+     */
+    static writeFile(srcPath: string, outPath: string, contents: any, overwrite?: boolean): Promise<void>;
+    /**
+     * Generates a copy of the source file at the desired output destination and performs a swap of all values of the
+     * variables specified.
+     *
+     * @param {string} srcPath The source file to copy.
+     * @param {string} outPath The destination file to generate.
+     * @param {any} variables The map of variable names to values to swap.
+     */
+    static copyFile(srcPath: string, outPath: string, variables?: any, overwrite?: boolean): Promise<void>;
+    /**
+     * Generates a copy of the source file at the desired output destination using binary copy mode.
+     *
+     * @param {string} srcPath The source file to copy.
+     * @param {string} outPath The destination file to generate.
+     * @param {Map<string,string>} variables The map of variable names to values to swap. Applies to outPath only.
+     */
+    static copyBinaryFile(srcPath: string, outPath: string, variables?: any): Promise<void>;
+    /**
+     * Performs a deep copy of a directory tree at the given srcPath to the specified output directory. Performs
+     * template replacement for all variables given and skips any files in the specified filter.
+     *
+     * @param {string} srcPath The path to the source directory to copy files from.
+     * @param {string} outPath The path to the destination directory to copy files to.
+     * @param {any} vars The map of template variables to perform replacement on.
+     * @param {array} excludeFilters The list of file extension filters to exclude during the copy process.
+     * @param {array} binaryFilters The list of file extension filters to copy as binary only.
+     * @param {boolean} force Set to `true` to force writing over any existing files.
+     */
+    static copyDirectory(srcPath: string, outPath: string, vars?: any, excludeFilters?: Array<string>, binaryFilters?: Array<string>, force?: boolean): Promise<void>;
+}

package/dist/types/JWTUtils.d.ts

@@ -0,0 +1,139 @@
+import jwt from "jsonwebtoken";
+/**
+ * Describes user data that is encoded in the payload of a JWT token.
+ *
+ * @author Jean-Philippe Steinmetz <rapidrests@gmail.com>
+ */
+export interface JWTUser {
+    /**
+     * The universally unique identifier of the user.
+     */
+    uid: string;
+    /**
+     * The unique name of the user.
+     */
+    name: string;
+    /**
+     * The list of roles (by name) that the user is apart of and will assume privileges for.
+     */
+    roles: string[];
+    /**
+     * Indicates if the user's e-mail address has been verified.
+     */
+    verified?: boolean;
+}
+/**
+ * Describes the payload data structure of signed JWT tokens.
+ */
+export interface JWTPayload extends jwt.JwtPayload {
+    /** Indicates if the payload profile has been compressed and with what method. */
+    compression?: "zlib";
+    /** Indicates if the payload profile has been encrypted. */
+    encryption?: boolean;
+    /** The user profile of the authenticated user the token is valid for. */
+    profile: JWTUser | string;
+    /** The unique identifier of the user's authentication session. */
+    sessionUid: string;
+}
+/**
+ * Describes the different types of support compression methods for JWT payloads.
+ */
+export declare enum JWTUtilsCompressionMethods {
+    /** Uses the zlib compression method. */
+    ZLIB = "zlib"
+}
+/**
+ * Describes the configuration options to be used with the `JWTUtilsConfig.payload` property.
+ *
+ * @author Jean-Philippe Steinmetz <rapidrests@gmail.com>
+ */
+export interface JWTUtilsPayloadOptions {
+    /**
+     * Set the method to use for compressing the payload profile, otherwise set to `null` for no compression.
+     */
+    compress?: JWTUtilsCompressionMethods;
+    /**
+     * Set to `true` to indicate that the JWT token payload is encrypted, otherwise set to `false`.
+     */
+    encrypt?: boolean;
+}
+/**
+ * Describes the configuration options to be used with the `JWTUtilsConfig.payload` property when performing password
+ * based encryption.
+ *
+ * @author Jean-Philippe Steinmetz <rapidrests@gmail.com>
+ */
+export interface JWTUtilsPayloadPasswordOptions extends JWTUtilsPayloadOptions {
+    /**
+     * The cryptographic cipher algorithm to use during encryption/decryption of a JWT token payload.
+     */
+    algorithm: string;
+    /**
+     * The initialization vector to use during encryption and decryption.
+     */
+    iv: Buffer;
+    /**
+     * The password to use when encrypting or decrypting JWT token payloads.
+     */
+    password: string;
+}
+/**
+ * Describes the configuration options to be used with the `JWTUtilsConfig.payload` property when performing
+ * key-based encryption.
+ *
+ * @author Jean-Philippe Steinmetz <rapidrests@gmail.com>
+ */
+export interface JWTUtilsPayloadKeyOptions extends JWTUtilsPayloadOptions {
+    /**
+     * The private key used to encrypt JWT token payloads.
+     */
+    private_key: string;
+    /**
+     * The public key used to decrypt JWT token payloads.
+     */
+    public_key: string;
+}
+/**
+ * Describes the configuration options to be used with `JWTUtils` functions.
+ *
+ * @author Jean-Philippe Steinmetz <rapidrests@gmail.com>
+ */
+export interface JWTUtilsConfig {
+    /**
+     * The secret to use for signing and verifying JWT tokens.
+     */
+    secret: jwt.Secret;
+    /**
+     * The options to use when performing JWT signing or verification.
+     */
+    options?: jwt.VerifyOptions;
+    /**
+     * The options that determine how JWT token payloads will be handled.
+     */
+    payload?: JWTUtilsPayloadOptions | JWTUtilsPayloadKeyOptions | JWTUtilsPayloadPasswordOptions;
+}
+/**
+ * Utility class for working with Json Web Token (JWT) authentication tokens.
+ *
+ * @author Jean-Philippe Steinmetz <rapidrests@gmail.com>
+ */
+export declare class JWTUtils {
+    /**
+     * Generates a new JWT token for the given config and user object. The user object must be a valid RapidREST
+     * user.
+     *
+     * @param config The JWT configuration to use when generating the token.
+     * @param user The user to encode into the token's payload.
+     * @param data Additional data to include the token's payload.
+     */
+    static createToken(config: JWTUtilsConfig, user: JWTUser, data?: any): string;
+    /**
+     * Decodes the given JWT authentication token using the provided configuration. If the token is not valid an
+     * error is thrown with the reason. Returns the encoded user object payload upon success.
+     *
+     * @param config The JWT configuration to use when validating the token.
+     * @param token The JWT token to validate.
+     * @returns The data encoded in the token's payload.
+     */
+    static decodeToken(config: JWTUtilsConfig, token: string): JWTPayload;
+}

package/dist/types/Logger.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Creates a new logger with the specified level and file name to output logs to.
+ *
+ * @param level The logging level to create the logger with.
+ * @param file The name (without an extension) of the file to output logs to.
+ */
+export declare const Logger: any;

package/dist/types/MessagingUtils.d.ts

@@ -0,0 +1,77 @@
+export interface OriginSettings {
+    email: string;
+    sms: string;
+}
+export interface TemplateMapBase {
+    [name: string]: Template;
+}
+export type TemplateMap = Omit<TemplateMapBase, "from"> & {
+    from: OriginSettings;
+};
+export interface Template {
+    enabled: boolean;
+    email_options?: any;
+    subject?: string;
+    html?: string;
+    slack_channel?: string;
+    slack_text?: string;
+    sms?: string;
+    sms_options?: any;
+    text?: string;
+}
+export interface SlackConfig {
+    name: string;
+    token: string;
+    signingSecret: string;
+}
+export interface SmtpAuth {
+    user: string;
+    pass: string;
+}
+export interface SmtpConfig {
+    host: string;
+    port: number;
+    secure: boolean;
+    auth?: SmtpAuth;
+}
+export interface TwilioConfig {
+    accountSid: string;
+    token: string;
+    options?: any;
+}
+/**
+ * Simple utility class for sending templated messages via e-mail, SMS and more.
+ */
+export declare class MessagingUtils {
+    protected slackApps: any[];
+    protected slackConfigs: any[];
+    private smtpConfig?;
+    private twilio?;
+    private twilioConfig;
+    private templates;
+    private logger?;
+    init(): Promise<void>;
+    /**
+     * Sends an email using the given template name and variables.
+     * @param templateName The name of the email template to send.
+     * @param templateVars The map of variables to inject into the template.
+     * @param options The map of additional options to pass into the sendMail function.
+     * @returns
+     */
+    sendEmail(templateName: string, templateVars: any, options?: any): Promise<any>;
+    /**
+     * Sends an Slack message using the given template name and variables.
+     * @param templateName The name of the Slack template to send.
+     * @param templateVars The map of variables to inject into the template.
+     * @returns
+     */
+    sendSlack(templateName: string, templateVars: any): Promise<any[] | undefined>;
+    /**
+     * Sends an SMS using the given template name and variables.
+     * @param templateName The name of the SMS template to send.
+     * @param templateVars The map of variables to inject into the template.
+     * @param options The map of additional options to pass into the sendMail function.
+     * @returns
+     */
+    sendSMS(templateName: string, templateVars: any, options?: any): Promise<any>;
+}

package/dist/types/NotificationsUtils.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Utility functions for sending push notifications to registered clients.
+ *
+ * @author Jean-Philippe Steinmetz
+ */
+export declare class NotificationUtils {
+    /** The redis client to use for broadcasting messages. */
+    private redis;
+    /**
+     * Initializes the utility using the given redis connection.
+     *
+     * @param {any} redis The redis connection to publish to.
+     */
+    constructor(redis: any);
+    /**
+     * Broadcasts a given message to all users.
+     *
+     * @param {any} type The type of message being sent.
+     * @param {string} action The action performed on the data (if applicable).
+     * @param {string} data The contents of the message to send.
+     */
+    broadcastMessage(type: any, action: string, data: any): void;
+    /**
+     * Sends a given message to the room or user with the specified uid(s).
+     *
+     * @param {string} uids The universally unique identifier of the room or user to send the message to.
+     * @param {string} type The type of message being sent.
+     * @param {string} action The action performed on the data (if applicable).
+     * @param {string} data The contents of the message to send to the room or user.
+     */
+    sendMessage(uids: string | string[], type: string, action: string, data: any): void;
+}

package/dist/types/OASUtils.d.ts

@@ -0,0 +1,54 @@
+export declare class OASUtils {
+    /**
+     * Gets the datastore definition with the specified name.
+     *
+     * @param spec The OpenAPI specification to search.
+     * @param name The name of the datastore to retrieve.
+     * @returns The definition for the datastore with the given name if found, otherwise `undefined`.
+     */
+    static getDatastore(spec: any, name: string): any;
+    /**
+     * Gets the specification object at the specified path.
+     *
+     * @param {any} spec The OpenAPI specification to reference.
+     * @param {string} path The path of the object to retrieve.
+     * @returns {any} The object at the specified path if found, otherwise `undefined`.
+     */
+    static getObject(spec: any, path: string): any;
+    /**
+     * Returns the first available response object for a 2XX response as defined by the provided Operation schema object.
+     *
+     * @param {any} obj The Operation schema object to search.
+     */
+    static getResponse(obj: any): any;
+    /**
+     * Returns the first available response content object for a 2XX response as defined by the provided Operation schema object.
+     *
+     * @param {any} obj The Operation schema object to search.
+     */
+    static getResponseContent(obj: any): any;
+    /**
+     * Retrieves the schema definition with the given name.
+     *
+     * @param {any} spec The OpenAPI specification object to reference.
+     * @param {string} name The name of the schema to retrieve.
+     * @returns {any} The schema definition with the given name.
+     */
+    static getSchema(spec: any, name: string): any;
+    /**
+     * Extracts the type information for a given schema Object definition.
+     *
+     * @param {any} schemaDef The schema definition object to extract type information from.
+     * @param {any} spec The entire OpenAPI specification object.
+     * @param {Function} convertDataType The function that converts OpenAPI Specification types to native types.
+     * @returns {any} A tuple containing the type, subType and subSchemaRef information.
+     */
+    static getTypeInfo(schemaDef: any, spec: any, convertDataType: Function): any;
+    /**
+     * Attempts to load the Open API specification at the given path or URL.
+     *
+     * @param {string} file The path or URL of the OpenAPI Specification file to load.
+     * @returns {Promise<any>} A promise whose result will be the loaded OpenAPI Specification as an object.
+     */
+    static loadSpec(file: string): Promise<any>;
+}

package/dist/types/ObjectFactory.d.ts

@@ -0,0 +1,77 @@
+import "reflect-metadata";
+/**
+ * The set of options to use when creating new instances of objects.
+ */
+export interface InstanceOptions {
+    args?: any[];
+    name?: string;
+    initialize?: boolean;
+}
+/**
+ * The `ObjectFactory` is a manager for creating objects based on registered
+ * class types. This allows for the tracking of multiple instances of objects
+ * so that references can be referenced by unique name.
+ *
+ * @author Jean-Philippe Steinmetz
+ */
+export declare class ObjectFactory {
+    /** A map for string fully qualified class names to their class types. */
+    readonly classes: Map<string, any>;
+    /** The global application configuration object. */
+    protected config: any;
+    /** A map for the unique name to the intance of a particular class type. */
+    readonly instances: Map<string, any>;
+    /** The application logging utility. */
+    protected logger: any;
+    constructor(config?: any, logger?: any);
+    /**
+     * Destroys the specified objects. If `undefined` is passed in, all objects managed by the factory are destroyed.
+     */
+    destroy(objs?: any | any[]): Promise<void>;
+    /**
+     * Deletes all instantiated objects.
+     */
+    clear(): void;
+    /**
+     * Deletes all instantiated objects and registered class types.
+     */
+    clearAll(): void;
+    /**
+     * Scans the given object for any properties with the `@Inject` decorator and assigns the correct values.
+     * @param obj The object to initialize with injected defaults
+     */
+    initialize<T>(obj: any): Promise<T>;
+    /**
+     * Searches an object for one or more functions that implement a `@Init` decorator.
+     *
+     * @param obj The object to search.
+     * @returns The list of functions that implements the `@Init` decorator if found, otherwise undefined.
+     */
+    getInitMethods(obj: any): Function[];
+    /**
+     * Returns the object instance with the given unique name. Unique names take the form `<ClassName>:<InstanceName>`.
+     * It is possible to only specifiy the `<ClassName>`, doing so will automatically look for the `<ClassName>:default`
+     * instance or the first found instance of the given type.
+     * @param nameOrType The unique name or class type of the object to retrieve.
+     * @returns The object instance associated with the given name if found, otherwise `undefined`.
+     */
+    getInstance<T>(nameOrType: any): T | undefined;
+    /**
+     * Creates a new instance of the class specified with the provided unique name or type and constructor arguments. If an existing
+     * object has already been created with the given name, that instance is returned, otherwise a new instance is created
+     * using the provided arguments.
+     *
+     * @param type The fully qualified name or type of the class to instantiate. If a type is given it's class name will be inferred
+     * via the constructor name.
+     * @param name The unique name to give the class instance. Set to `undefined` if you wish to force a new object is created.
+     * @param initialize Set to `true` to initialize the object after creation, otherwise set to `false`. Default is `true`.
+     * @param args The set of constructor arguments to use during construction
+     */
+    newInstance<T>(type: any, options?: InstanceOptions): T | Promise<T>;
+    /**
+     * Registers the given class type for the provided fully qualified name.
+     * @param clazz The class type to register.
+     * @param fqn The fully qualified name of the class to register. If not specified, the class name will be used.
+     */
+    register(clazz: any, fqn?: string): void;
+}

package/dist/types/ObjectUtils.d.ts

@@ -0,0 +1,17 @@
+import "reflect-metadata";
+/**
+ * Utility class for working with objects.
+ *
+ * @author Jean-Philippe Steinmetz
+ */
+export declare class ObjectUtils {
+    /**
+     * Performs validation of the given object or array. Validation is performed by scanning the object class for properties
+     * decorated with `@Validator` and executing the provided validation function.
+     *
+     * @param obj The object or array of objects to validate.
+     * @param clazz The class type that contains the validation metadata.
+     * @param recurse Set to `true` to validate all child objects.
+     */
+    static validate(obj: any, clazz?: any, recurse?: boolean): void;
+}

package/dist/types/StringUtils.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Utility functions for working with strings.
+ *
+ * @author Jean-Philippe Steinmetz
+ */
+export declare class StringUtils {
+    /**
+     * Returns a list of all parameters contained within the string. A parameter is a bracket delimited substring
+     * (e.g. /my/{key}/with/{id}).
+     *
+     * @param {any} str The string to search for parameters.
+     * @returns {array} A list of parameters contained in the provided string.
+     */
+    static getParameters(str: string): Array<string>;
+    /**
+     * Performs a search and replace on the provided contents with the map of variable replacements. The contents
+     * must use Mustache formatted tokens such as `{{toreplace}}`.
+     *
+     * @param {string} contents The stringt to perform the find and replace on.
+     * @param {object} variables A map of key=>value pairs to search for and replace.
+     */
+    static findAndReplace(contents: string, variables: any): string;
+    /**
+     * Replaces all instances of the match regex pattern with the contents of the inner regular expression pattern for
+     * the given string.
+     *
+     * e.g.
+     *
+     * let result = replaceAll('/my/path/{id}', new RegExp('\\{([^\\}]+)\\}'), ':');
+     * console.log(result); // -> /my/path/:id
+     *
+     * @param {string} str The string to perform replacement on.
+     * @param {RegExp} match The regular expression pattern to match containing an outer and inner pattern.
+     * @param {string} prefix The prefix to prepend the replacement text with.
+     * @returns {string} The fully replaced contents of the string.
+     */
+    static replaceAll(str: string, match: string | RegExp, prefix: string): string;
+    /**
+     * Converts the first character in the given string to be lowercase (e.g. myVariable).
+     *
+     * @param {string} str The string to convert to camelCase.
+     * @returns {string} The string converted to camelCase.
+     */
+    static toCamelCase(str: string): string;
+    /**
+     * Converts the first character in the given string to be uppercase (e.g. MyVariable).
+     *
+     * @param {string} str The string to convert to PascalCase.
+     * @returns {string} The string converted to PascalCase.
+     */
+    static toPascalCase(str: string): string;
+}

package/dist/types/TelemetryUtils.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Describes the required fields when creating a new telemetry event.
+ *
+ * @author Jean-Philippe Steinmetz <rapidrests@gmail.com>
+ */
+export interface NewEvent {
+    /** The type of event begin recorded. */
+    type: string;
+}
+/**
+ * Describes a single telemetry event. A telemetry event is when something occurs in the system.
+ *
+ * @author Jean-Philippe Steinmetz <rapidrests@gmail.com>
+ */
+export declare class Event implements NewEvent {
+    /**
+     * The universally unique identifier of the event.
+     */
+    readonly uid: string;
+    /**
+     * The name of the environment that the event originated from. This is typically `dev` or `prod`.
+     */
+    readonly environment: string;
+    /**
+     * The unique name of the service or client that the event originated from.
+     */
+    readonly origin: string;
+    /**
+     * The date and time that the event occured.
+     */
+    readonly timestamp: Date;
+    /**
+     * The type of event being recorded.
+     */
+    readonly type: string;
+    /**
+     * The universally unique identifer of the user that sent the event.
+     */
+    readonly userId: string;
+    constructor(config: any, userId: string, data: NewEvent);
+}
+/**
+ * Provides a common set of static functions for recording and working with telemetry `Event` instances.
+ *
+ * The `init` function must be called before any other function can be called.
+ *
+ * The `record` function is used to send an event to a configured `telemetry_services` service for permanent storage.
+ *
+ * The `on` function allows code within the same application or service to listen for outgoing events that have been
+ * sent via the `record` function.
+ *
+ * @author Jean-Philippe Steinmetz <rapidrests@gmail.com>
+ */
+export declare class EventUtils {
+    private static initialized;
+    private static config;
+    private static listeners;
+    private static logger;
+    private static token;
+    private static userId;
+    /**
+     * Initializes `EventUtils` with the provided defaults.
+     *
+     * @param config The application configuration to use.
+     * @param logger The logging utility to use.
+     * @param jwtToken The user's JWT token to send telemetry events on behalf of.
+     */
+    static init(config: any, logger: any, jwtToken: string): void;
+    /**
+     * Sends the given event to the telemetry service for permanent recording.
+     *
+     * @param evt The event to send and record.
+     * @param type The type of event to record. Overrides any `type` value set in `evt`.
+     */
+    static record(evt: NewEvent | any, type?: string): Promise<void>;
+    /**
+     * Registers a `callback` function to receive notifications of recorded events of the given `type`. Note that only
+     * events originating from the same application or service will be notified.
+     *
+     * @param type The type of event to be notified of.
+     * @param callback The function to call when an event is recorded.
+     */
+    static on(type: string, callback: Function): void;
+}