@automationcloud/robot - npm Package Compare versions

Comparing version 1.0.0-rc.10 to 1.0.0-rc.11

out/main/exception.d.ts

@@ -7,2 +7,5 @@ export interface ExceptionSpec {
 }
+/**
+ * An error with formalized code and optional details.
+ */
 export declare class Exception extends Error {
@@ -9,0 +12,0 @@ code: string;

out/main/exception.js

@@ -17,2 +17,5 @@ "use strict";
 exports.Exception = void 0;
+/**
+ * An error with formalized code and optional details.
+ */
 class Exception extends Error {
@@ -19,0 +22,0 @@ constructor(spec) {

out/main/job.d.ts

@@ -1,5 +0,1 @@
-export interface JobInitParams {
-    input: JobInputObject;
-    category: JobCategory;
-}
 /**
@@ -37,2 +33,9 @@ * Unified interface for running Autopilot scripts.
     /**
+     * If job is waiting for input (i.e. due to input request by script and not yet submitted),
+     * then this method returns the requested input key, otherwise `null` is returned.
+     *
+     * @public
+     */
+    abstract getAwaitingInputKey(): string | null;
+    /**
      * Submits an input with specified `key` and `data`.
@@ -92,14 +95,17 @@ *
     /**
-     * Subscribes to `awaitingInput` event for specified input key.
+     * Subscribes to `awaitingInput` event for specified input key and optionally fulfills
+     * the input request with data returned by handler funciton.
      *
      * When input with specified `key` is requested by script, the supplied `fn` handler is invoked.
-     * The result of the handler is sent as input data for that key, fulfilling the input request.
      *
+     * Unless the handler returns `undefined`, the result value is sent as input data for that key,
+     * fulfilling the input request.
+     *
      * Use this to handle deferred inputs.
      *
-     * @param key requested input key
+     * @param key requested input key, `*` to receive all events.
      * @param fn handler callback, can be either synchronous or asynchronous; the return value is
      *  submitted as input data for specified input `key`
      */
-    onAwaitingInput(key: string, fn: () => any | Promise<any>): JobEventHandler;
+    onAwaitingInput(key: string, fn: (key: string) => any | Promise<any>): JobEventHandler;
     /**
@@ -150,2 +156,21 @@ * Subscribes to `output` event for specified output `key`.
 }
+/**
+ * Job initialization parameters, provided when the job is being created using `robot.createJob()`.
+ */
+export interface JobInitParams {
+    /**
+     * Initial job inputs (provided as objects).
+     */
+    input: JobInputObject;
+    /**
+     * Job category, used for filtering jobs in Automation Cloud dashboard.
+     */
+    category: JobCategory;
+}
+/**
+ * Job can be in one particular state at any given time.
+ *
+ * Note: not all states are necessarily supported by underlying mechanism. For example,
+ * 3-D Secure handling is not supported by `LocalRobot` so local jobs will never be in `AWAITING_TDS` state.
+ */
 export declare enum JobState {
@@ -161,2 +186,5 @@ CREATED = "created",
 }
+/**
+ * Indicates whether the job is live or test, useful for filtering jobs in dashboard.
+ */
 export declare enum JobCategory {
@@ -166,20 +194,72 @@ LIVE = "live",
 }
+/**
+ * Describes the reason of job failure.
+ */
 export interface JobError {
+    /**
+     * Error code in PascalCase, typically constrained by schema.
+     */
     code: string;
+    /**
+     * A designation of the root cause of error:
+     *
+     * - `client` indicates the class of errors that involve client actions
+     *   (e.g. invalid inputs supplied, job cancelled, etc.)
+     * - `server` indicates platform-related failure (e.g. worker crash, timeout, API unavailable, etc.)
+     * - `website` indicates a known limitation with the website (e.g. an unsupported feature, flow or layout)
+     */
     category: 'client' | 'server' | 'website';
+    /**
+     * If applicable, human-readable message for logging and debugging.
+     *
+     * Note: implementations should never depend on the structure of this string.
+     */
     message: string;
+    /**
+     * Arbitrary details for logging and debugging.
+     *
+     * Note: implementations should never depend on the structure of this object.
+     */
     details?: any;
 }
-export interface JobOutput {
+/**
+ * Job inputs are the primary means of supplying data to automations.
+ *
+ * Data is supplied by client in key-value format. Keys must be in camelCase.
+ */
+export interface JobInput {
     key: string;
     data: any;
 }
-export interface JobInput {
+/**
+ * Job outputs are the primary means of receiving data from automations.
+ *
+ * Data is emitted by script in key-value format. Keys must be in camelCase.
+ */
+export interface JobOutput {
     key: string;
     data: any;
 }
+/**
+ * Describes initial job inputs in object representation.
+ */
 export interface JobInputObject {
     [key: string]: any;
 }
+/**
+ * Event subscription methods like `onOutput` return handlers which can subsequently be invoked
+ * with zero arguments to unsubscribe from the event.
+ *
+ * ```ts
+ * const unsubscribe = job.onOutput('someKey', async data => { ... });
+ * // ...
+ * unsubscribe();
+ * ```
+ */
 export declare type JobEventHandler = () => void;
+/**
+ * Unified event emitter for passing internal job events between components.
+ *
+ * @internal
+ */
 export interface JobEventBus {
@@ -186,0 +266,0 @@ emit(event: 'input', input: JobInput): boolean;

out/main/job.js

@@ -87,10 +87,13 @@ "use strict";
     /**
-     * Subscribes to `awaitingInput` event for specified input key.
+     * Subscribes to `awaitingInput` event for specified input key and optionally fulfills
+     * the input request with data returned by handler funciton.
      *
      * When input with specified `key` is requested by script, the supplied `fn` handler is invoked.
-     * The result of the handler is sent as input data for that key, fulfilling the input request.
      *
+     * Unless the handler returns `undefined`, the result value is sent as input data for that key,
+     * fulfilling the input request.
+     *
      * Use this to handle deferred inputs.
      *
-     * @param key requested input key
+     * @param key requested input key, `*` to receive all events.
      * @param fn handler callback, can be either synchronous or asynchronous; the return value is
@@ -101,5 +104,7 @@ *  submitted as input data for specified input `key`
         return this._createJobEventHandler('awaitingInput', async (requestedKey) => {
-            if (requestedKey === key) {
-                const data = await fn();
-                await this.submitInput(key, data);
+            if (key === '*' || requestedKey === key) {
+                const data = await fn(requestedKey);
+                if (data !== undefined) {
+                    await this.submitInput(key, data);
+                }
             }
@@ -176,2 +181,8 @@ });
 exports.Job = Job;
+/**
+ * Job can be in one particular state at any given time.
+ *
+ * Note: not all states are necessarily supported by underlying mechanism. For example,
+ * 3-D Secure handling is not supported by `LocalRobot` so local jobs will never be in `AWAITING_TDS` state.
+ */
 var JobState;
@@ -188,2 +199,5 @@ (function (JobState) {
 })(JobState = exports.JobState || (exports.JobState = {}));
+/**
+ * Indicates whether the job is live or test, useful for filtering jobs in dashboard.
+ */
 var JobCategory;
@@ -190,0 +204,0 @@ (function (JobCategory) {

out/main/logger.d.ts

@@ -0,1 +1,8 @@
+/**
+ * Standard logging interface, compatible with `console`.
+ *
+ * Use this interface to provide your own logging system to Robot API
+ * (either directly or via an adapter).
+ * ```
+ */
 export interface Logger {
@@ -2,0 +9,0 @@ info(message: string, object?: any): void;

out/main/robot.d.ts

 import { Job, JobInitParams } from './job';
 import { Logger } from './logger';
+/**
+ * A Robot API instance which is used to execute a particular script.
+ *
+ * Robot instance is scoped to a script or service and can be used
+ * to create multiple jobs with the same configuration.
+ * For creating jobs that execute different scripts, separate Robot instances should be created.
+ */
 export declare abstract class Robot {
     logger: Logger;
+    /**
+     * Creates a new job which conceptually results in starting an automation
+     * and starts tracking its lifecycle events (i.e. emitted outputs, requested inputs, success,
+     * failures, etc.)
+     *
+     * The exact behaviour depends on the underlying mechanism:
+     *
+     * - `LocalRobot` will run a provided script using the embedded `Engine`
+     *   connected to a local Chromium instance;
+     * - `CloudRobot` submits a new job to Automation Cloud API and starts tracking it
+     *   by polling its state.
+     *
+     * The job is automatically tracked after creation. The tracking stops after the job
+     * reaches one of the final states (`success`, `fail`). For this reason it is recommended
+     * that `await job.waitForCompletion()` is always included to prevent dangling promises
+     * and unhandled promise rejections.
+     *
+     * Please refer to specific implementations for more details.
+     *
+     * @param options Job initilalization parameters (includes `category` and `input`).
+     */
     createJob(options?: Partial<JobInitParams>): Promise<Job>;
+    /**
+     * An actual implementation of job create functionality.
+     *
+     * @param params
+     * @internal
+     */
     protected abstract _createJob(params: JobInitParams): Promise<Job>;
 }
 //# sourceMappingURL=robot.d.ts.map

out/main/robot.js

@@ -18,2 +18,9 @@ "use strict";
 const job_1 = require("./job");
+/**
+ * A Robot API instance which is used to execute a particular script.
+ *
+ * Robot instance is scoped to a script or service and can be used
+ * to create multiple jobs with the same configuration.
+ * For creating jobs that execute different scripts, separate Robot instances should be created.
+ */
 class Robot {
@@ -23,2 +30,23 @@ constructor() {
     }
+    /**
+     * Creates a new job which conceptually results in starting an automation
+     * and starts tracking its lifecycle events (i.e. emitted outputs, requested inputs, success,
+     * failures, etc.)
+     *
+     * The exact behaviour depends on the underlying mechanism:
+     *
+     * - `LocalRobot` will run a provided script using the embedded `Engine`
+     *   connected to a local Chromium instance;
+     * - `CloudRobot` submits a new job to Automation Cloud API and starts tracking it
+     *   by polling its state.
+     *
+     * The job is automatically tracked after creation. The tracking stops after the job
+     * reaches one of the final states (`success`, `fail`). For this reason it is recommended
+     * that `await job.waitForCompletion()` is always included to prevent dangling promises
+     * and unhandled promise rejections.
+     *
+     * Please refer to specific implementations for more details.
+     *
+     * @param options Job initilalization parameters (includes `category` and `input`).
+     */
     async createJob(options = {}) {
@@ -25,0 +53,0 @@ return await this._createJob(Object.assign({ category: job_1.JobCategory.TEST, input: {} }, options));

package.json

 {
     "name": "@automationcloud/robot",
-    "version": "1.0.0-rc.10",
+    "version": "1.0.0-rc.11",
     "description": "API for running scripts on Automation Cloud",
@@ -28,3 +28,3 @@ "main": "out/main/index.js",
     },
-    "gitHead": "dbb79b22705aa18fd0b26661af800b7e706988d2"
+    "gitHead": "b323c9bb851732ed2dde763dfed9c517eb90a446"
 }

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

47798

increased by16.97%

Lines of code

678

increased by33.2%

No dependency changes