@prismatic-io/spectral 3.1.0

package/dist/types/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * This file exports types from all other files in types/, so users can simply
+ * `import { DesiredType } from "@prismatic-io/spectral"`
+ */
+export * from "./Credential";
+export * from "./AuthorizationDefinition";
+export * from "./ActionDefinition";
+export * from "./Inputs";
+export * from "./PerformReturn";
+export * from "./DisplayDefinition";
+export * from "./ActionInputParameters";
+export * from "./ActionLogger";
+export * from "./ActionPerformFunction";
+export * from "./InputFieldType";
+export * from "./conditional-logic";

package/dist/types/index.js

@@ -0,0 +1,27 @@
+"use strict";
+/**
+ * This file exports types from all other files in types/, so users can simply
+ * `import { DesiredType } from "@prismatic-io/spectral"`
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    Object.defineProperty(o, k2, { enumerable: true, get: function() { return m[k]; } });
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./Credential"), exports);
+__exportStar(require("./AuthorizationDefinition"), exports);
+__exportStar(require("./ActionDefinition"), exports);
+__exportStar(require("./Inputs"), exports);
+__exportStar(require("./PerformReturn"), exports);
+__exportStar(require("./DisplayDefinition"), exports);
+__exportStar(require("./ActionInputParameters"), exports);
+__exportStar(require("./ActionLogger"), exports);
+__exportStar(require("./ActionPerformFunction"), exports);
+__exportStar(require("./InputFieldType"), exports);
+__exportStar(require("./conditional-logic"), exports);

package/dist/types/server-types.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Types defined in this module describe the shape of objects that are
+ * sent to Prismatic's API when a component is published. Types defined
+ * should not generally be imported directly, but they're the types of
+ * objects that are created by `component()` and `action()` helper functions.
+ */
+/// <reference types="node" />
+/** Import shared types from types/ */
+import { ActionContext } from "./ActionPerformFunction";
+import { AuthorizationDefinition } from "./AuthorizationDefinition";
+import { ActionDisplayDefinition, ComponentDisplayDefinition } from "./DisplayDefinition";
+import { InputFieldChoice, InputFieldCollection } from "./Inputs";
+/** Defines attributes of a Component. */
+interface ComponentBase<T extends boolean> {
+    /** Specifies unique key for this Component. */
+    key: string;
+    /** Specifies if this Component is available for all Organizations or only your own @default false */
+    public?: T;
+    /** Defines how the Component is displayed in the Prismatic interface. */
+    display: ComponentDisplayDefinition<T>;
+    /** @deprecated Version of the Component. */
+    version?: string;
+    /** Specifies the supported Actions of this Component. */
+    actions: Record<string, Action>;
+}
+export declare type Component<T extends boolean> = ComponentBase<T> & (T extends true ? {
+    /** Specified the URL for the Component Documentation. */
+    documentationUrl: string;
+} : {
+    /** Specified the URL for the Component Documentation. */
+    documentationUrl?: string;
+});
+/** Configuration of an Action. */
+export interface Action {
+    /** Key used for the Actions map and to uniquely identify this Component in your tenant. */
+    key: string;
+    /** Defines how the Action is displayed in the Prismatic interface. */
+    display: ActionDisplayDefinition;
+    /** Function to perform when this Action is used and invoked. */
+    perform: ActionPerformFunction;
+    /** InputFields to present in the Prismatic interface for configuration of this Action. */
+    inputs: InputField[];
+    /** Specifies Authorization settings, if applicable */
+    authorization?: AuthorizationDefinition;
+    /** Optional attribute that specifies whether an Action will terminate execution.*/
+    terminateExecution?: boolean;
+    /** Determines whether an Action will allow Conditional Branching.*/
+    allowsBranching?: boolean;
+    /**Static Branch names associated with an Action. */
+    staticBranchNames?: string[];
+    /**The Input associated with Dynamic Branching.*/
+    dynamicBranchInput?: string;
+    /**An example of the payload outputted by an Action*/
+    examplePayload?: ServerPerformDataStructureReturn | ServerPerformBranchingDataStructureReturn;
+}
+/** Collection of input parameters provided by the user or previous steps' outputs */
+interface ActionInputParameters {
+    [key: string]: unknown;
+}
+/** Used to represent returning conventional data and does not require content type to be specified */
+export interface ServerPerformDataStructureReturn {
+    /** Data structure to return from the action */
+    data: boolean | number | string | Record<string, unknown> | unknown[] | unknown;
+    /** The Content Type of the payload data that can be optionally specified */
+    contentType?: string;
+    /** The HTTP Status code that will be used if this terminates a synchronous invocation  */
+    statusCode?: number;
+    /** An optional object, the keys and values of which will be persisted in the instanceState and available for subsequent actions and executions */
+    state?: Record<string, unknown>;
+}
+/** Used to represent a binary or serialized data return as content type must be specified */
+interface ServerPerformDataReturn {
+    /** Data payload containing data of the specified contentType */
+    data: Buffer | string | unknown;
+    /** The Content Type of the payload data */
+    contentType: string;
+    /** The HTTP Status code that will be used if this terminates a synchronous invocation  */
+    statusCode?: number;
+    /** An optional object, the keys and values of which will be persisted in the instanceState and available for subsequent actions and executions */
+    state?: Record<string, unknown>;
+}
+/** Used to represent a branching return of conventional data and does not require content type to be specified */
+export interface ServerPerformBranchingDataStructureReturn extends ServerPerformDataStructureReturn {
+    /** Name of the Branch to take. */
+    branch: string;
+}
+/** Used to represent a binary or serialized data branching return as content type must be specified */
+interface ServerPerformBranchingDataReturn extends ServerPerformDataReturn {
+    /** Name of the Branch to take. */
+    branch: string;
+}
+/** Required return type of all action perform functions */
+declare type PerformReturn = ServerPerformDataStructureReturn | ServerPerformBranchingDataStructureReturn | ServerPerformDataReturn | ServerPerformBranchingDataReturn | void;
+/** Definition of the function to perform when an Action is invoked. */
+declare type ActionPerformFunction = (context: ActionContext, params: ActionInputParameters) => Promise<PerformReturn>;
+declare type InputField = DefaultInputField | CodeInputField;
+/** Defines attributes of a InputField. */
+interface DefaultInputField {
+    /** Unique identifier of the InputField. Must be unique within an Action. */
+    key: string;
+    /** Interface label of the InputField. */
+    label: string;
+    /** Data type the InputField will collect. */
+    type: InputFieldType;
+    /** Collection type of the InputField */
+    collection?: InputFieldCollection;
+    /** Text to show as the InputField placeholder. */
+    placeholder?: string;
+    /** Default value for this field. */
+    default?: string;
+    /** Additional text to give guidance to the user configuring the InputField. */
+    comments?: string;
+    /** Example valid input for this InputField. */
+    example?: string;
+    /** Indicate if this InputField is required. */
+    required?: boolean;
+    /** Dictates possible choices for the input. */
+    model?: InputFieldChoice[];
+}
+interface CodeInputField extends DefaultInputField {
+    type: "code";
+    language?: string;
+}
+/** InputField type enumeration. */
+declare type InputFieldType = "string" | "text" | "password" | "boolean" | "code" | "data" | "conditional";
+/** Binary data payload */
+export interface DataPayload {
+    /** Raw binary data as a Buffer */
+    data: Buffer;
+    /** Content type of data contained within this payload */
+    contentType: string;
+    /** Suggested extension to use when writing the data */
+    suggestedExtension?: string;
+}
+export {};

package/dist/types/server-types.js

@@ -0,0 +1,8 @@
+"use strict";
+/**
+ * Types defined in this module describe the shape of objects that are
+ * sent to Prismatic's API when a component is published. Types defined
+ * should not generally be imported directly, but they're the types of
+ * objects that are created by `component()` and `action()` helper functions.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/util.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The `util` module provides a set of functions commonly needed to author custom components.
+ * Many functions in the `util` module are used to coerce data into a particular type, and can be accessed through `util.types`.
+ * For example, `util.types.toInt("5.5")` will return an integer, `5`.
+ */
+import { DataPayload } from "./types/server-types";
+import { KeyValuePair } from "./types";
+declare const _default: {
+    types: {
+        isBool: (value: unknown) => value is boolean;
+        toBool: (value: unknown, defaultValue?: boolean | undefined) => boolean;
+        isInt: (value: unknown) => value is number;
+        toInt: (value: unknown, defaultValue?: number | undefined) => number;
+        isNumber: (value: unknown) => boolean;
+        toNumber: (value: unknown, defaultValue?: number | undefined) => number;
+        isBigInt: (value: unknown) => value is bigint;
+        toBigInt: (value: unknown) => BigInt;
+        isDate: (value: unknown) => value is Date;
+        toDate: (value: unknown) => Date;
+        isUrl: (value: string) => boolean;
+        isBufferDataPayload: (value: unknown) => boolean;
+        toBufferDataPayload: (value: unknown) => DataPayload;
+        isData: (value: unknown) => boolean;
+        toData: (value: unknown) => DataPayload;
+        toString: (value: unknown, defaultValue?: string) => string;
+        keyValPairListToObject: (kvpList?: KeyValuePair<unknown>[]) => Record<string, unknown>;
+        isJSON: (value: string) => boolean;
+    };
+    docs: {
+        formatJsonExample: (input: unknown) => string;
+    };
+};
+export default _default;

package/dist/util.js

@@ -0,0 +1,337 @@
+"use strict";
+/**
+ * The `util` module provides a set of functions commonly needed to author custom components.
+ * Many functions in the `util` module are used to coerce data into a particular type, and can be accessed through `util.types`.
+ * For example, `util.types.toInt("5.5")` will return an integer, `5`.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/** */
+const parseISO_1 = __importDefault(require("date-fns/parseISO"));
+const isValid_1 = __importDefault(require("date-fns/isValid"));
+const isDate_1 = __importDefault(require("date-fns/isDate"));
+const valid_url_1 = require("valid-url");
+/**
+ * Determine if a variable is a boolean (true or false).
+ *
+ * - `util.types.isBool(false)` will return `true`, since `false` is a boolean.
+ * - `util.types.isBool("Hello")` will return `false`, since `"Hello"` is not a boolean.
+ *
+ * @param value The variable to test.
+ * @returns True if the value is a boolean, or false otherwise.
+ */
+const isBool = (value) => value === true || value === false;
+/**
+ * Convert truthey (true, "t", "true", "y", "yes") values to boolean `true`,
+ * and falsey (false, "f", "false", "n", "no") values to boolean `false`.
+ * Truthy/falsey checks are case-insensitive.
+ *
+ * In the event that `value` is undefined or an empty string, a default value can be provided.
+ * For example, `util.types.toBool('', true)` will return `true`.
+ *
+ * @param value The value to convert to a boolean.
+ * @param defaultValue The value to return if `value` is undefined or an empty string.
+ * @returns The boolean equivalent of the truthey or falsey `value`.
+ */
+const toBool = (value, defaultValue) => {
+    if (isBool(value)) {
+        return value;
+    }
+    if (typeof value === "string") {
+        const lowerValue = value.toLowerCase();
+        if (["t", "true", "y", "yes"].includes(lowerValue)) {
+            return true;
+        }
+        else if (["f", "false", "n", "no"].includes(lowerValue)) {
+            return false;
+        }
+    }
+    return Boolean(value || defaultValue);
+};
+/**
+ * This function checks if value is an integer.
+ * `util.types.isInt(5)` returns true, while `util.types.isInt("5")` or `util.types.isInt(5.5)` returns false.
+ * @param value The variable to test.
+ * @returns This function returns true or false, depending on if `value` is an integer.
+ */
+const isInt = (value) => Number.isInteger(value);
+/**
+ * This function converts a variable to an integer if possible.
+ * `util.types.toInt(5.5)` will return `5`.  `util.types.toInt("20.3")` will return `20`.
+ *
+ * In the event that `value` is undefined or an empty string, a default value can be provided.
+ * For example, `util.types.toInt('', 1)` will return `1`.
+ *
+ * This function will throw an exception if `value` cannot be coerced to an integer.
+ * @param value The value to convert to an integer.
+ * @param defaultValue The value to return if `value` is undefined, an empty string, or not able to be coerced.
+ * @returns This function returns an integer if possible.
+ */
+const toInt = (value, defaultValue) => {
+    if (isInt(value))
+        return value;
+    // Turn a float into an int
+    if (typeof value === "number") {
+        return ~~value;
+    }
+    if (typeof value === "string") {
+        const intValue = Number.parseInt(value);
+        if (!Number.isNaN(intValue)) {
+            return intValue;
+        }
+    }
+    if (typeof value === "undefined" || value === "") {
+        return defaultValue || 0;
+    }
+    if (defaultValue) {
+        return defaultValue;
+    }
+    throw new Error(`Value '${value}' cannot be coerced to int.`);
+};
+/**
+ * Determine if a variable is a number, or can easily be coerced into a number.
+ *
+ * - `util.types.isNumber(3.21)` will return `true`, since `3.21` is a number.
+ * - `util.types.isBool("5.5")` will return `true`, since the string `"5.5"` can easily be coerced into a number.
+ * - `util.types.isBool("Hello")` will return `false`, since `"Hello"` is not a number.
+ *
+ * @param value The varible to test.
+ * @returns This function returns true if `value` can easily be coerced into a number, and false otherwise.
+ */
+const isNumber = (value) => !Number.isNaN(Number(value));
+/**
+ * This function coerces a value (number or string) into a number.
+ * In the event that `value` is undefined or an empty string, a `defaultValue` can be provided, or zero will be returned.
+ * If `value` is not able to be coerced into a number but is defined, an error will be thrown.
+ *
+ * - `util.types.toNumber("3.22")` will return the number `3.22`.
+ * - `util.types.toNumber("", 5.5)` will return the default value `5.5`, since `value` was an empty string.
+ * - `util.types.toNumber(undefined)` will return `0`, since `value` was undefined and no `defaultValue` was given.
+ * - `util.types.toNumber("Hello")` will throw an error, since the string `"Hello"` cannot be coerced into a number.
+ * @param value The value to turn into a number.
+ * @param defaultValue The value to return if `value` is undefined or an empty string.
+ * @returns This function returns the numerical version of `value` if possible, or the `defaultValue` if `value` is undefined or an empty string.
+ */
+const toNumber = (value, defaultValue) => {
+    if (isNumber(value)) {
+        return Number(value);
+    }
+    if (typeof value === "undefined" || value === "") {
+        return defaultValue || 0;
+    }
+    throw new Error(`Value '${value}' cannot be coerced to a number.`);
+};
+/**
+ * @param value The value to test
+ * @returns This function returns true if the type of `value` is a bigint, or false otherwise.
+ */
+const isBigInt = (value) => typeof value === "bigint";
+/**
+ * This function coerces a provided value into a bigint if possible.
+ * The provided `value` must be a bigint, integer, string representing an integer, or a boolean.
+ *
+ * - `util.types.toBigInt(3)` will return `3n`.
+ * - `util.types.toBigInt("-5")` will return `-5n`.
+ * - `util.types.toBigInt(true)` will return `1n` (and `false` will return `0n`).
+ * - `util.types.toBigInt("5.5")` will throw an error, as `5.5` is not an integer.
+ * @param value The value to coerce to bigint.
+ * @returns This function returns the bigint representation of `value`.
+ */
+const toBigInt = (value) => {
+    if (isBigInt(value)) {
+        return value;
+    }
+    try {
+        return BigInt(toString(value));
+    }
+    catch (error) {
+        throw new Error(`Value '${value}' cannot be coerced to bigint.`);
+    }
+};
+/** This function returns true if `value` is a variable of type `Date`, and false otherwise. */
+const isDate = (value) => isDate_1.default(value);
+/**
+ * This function parses an ISO date if possible, or throws an error if the value provided
+ * cannot be coerced into a Date object.
+ *
+ * - `util.types.toDate(new Date('1995-12-17T03:24:00'))` will return `Date('1995-12-17T09:24:00.000Z')` since a `Date` object was passed in.
+ * - `util.types.toDate('2021-03-20')` will return `Date('2021-03-20T05:00:00.000Z')` since a valid ISO date was passed in.
+ * - `parseISODate('2021-03-20-05')` will throw an error since `value` was not a valid ISO date.
+ * @param value The value to turn into a date.
+ * @returns The date equivalent of `value`.
+ */
+const toDate = (value) => {
+    if (isDate(value)) {
+        return value;
+    }
+    if (typeof value === "string") {
+        const dt = parseISO_1.default(value);
+        if (isValid_1.default(dt)) {
+            return dt;
+        }
+    }
+    throw new Error(`Value '${value}' cannot be coerced to date.`);
+};
+/**
+ * This function tests if the string provided is a valid URL, and returns `true` if the URL is valid.
+ * Note: this function only tests that the string is a syntactically correct URL; it does not check
+ * if the URL is web accessible.
+ *
+ * - `util.types.isUrl('https://prismatic.io')` will return true.
+ * - `util.types.isUrl('https:://prismatic.io')` will return false due to the extraneous `:` symbol.
+ * @param value The URL to test.
+ * @returns This function returns true if `value` is a valid URL, and false otherwise.
+ */
+const isUrl = (value) => valid_url_1.isWebUri(value) !== undefined;
+/**
+ * This function helps to transform key-value lists to objects.
+ * This is useful for transforming inputs that are key-value collections into objects.
+ *
+ * For example, an input that is a collection might return `[{key: "foo", value: "bar"},{key: "baz", value: 5}]`.
+ * If that array were passed into `util.types.keyValPairListToObject()`, an object would be returned of the form
+ * `{foo: "bar", baz: 5}`.
+ * @param kvpList An array of objects with `key` and `value` properties.
+ */
+const keyValPairListToObject = (kvpList = []) => {
+    return kvpList.reduce((result, { key, value }) => (Object.assign(Object.assign({}, result), { [key]: value })), {});
+};
+/**
+ * This function tests if the object provided is a Prismatic `DataPayload` object.
+ * A `DataPayload` object is an object with a `data` attribute, and optional `contentType` attribute.
+ *
+ * @param value The value to test
+ * @returns This function returns true if `value` is a DataPayload object, and false otherwise.
+ */
+const isBufferDataPayload = (value) => {
+    return value instanceof Object && "data" in value;
+};
+/**
+ * Many libraries for third-party API that handle binary files expect `Buffer` objects.
+ * This function helps to convert strings, Uint8Arrays, and Arrays to a data structure
+ * that has a Buffer and a string representing `contentType`.
+ *
+ * You can access the buffer like this:
+ *  `const { data, contentType } = util.types.toBufferDataPayload(someData);`
+ *
+ * If `value` cannot be converted to a Buffer, an error will be thrown.
+ * @param value The string, Buffer, Uint8Array, or Array to convert to a Buffer.
+ * @returns This function returns an object with two keys: `data`, which is a `Buffer`, and `contentType`, which is a string.
+ */
+const toBufferDataPayload = (value) => {
+    if (isBufferDataPayload(value)) {
+        return value;
+    }
+    if (typeof value === "string") {
+        return {
+            data: Buffer.from(value, "utf-8"),
+            contentType: "text/plain",
+        };
+    }
+    if (value instanceof Buffer) {
+        return {
+            data: value,
+            contentType: "application/octet-stream",
+        };
+    }
+    if (value instanceof Uint8Array) {
+        return {
+            data: Buffer.from(value),
+            contentType: "application/octet-stream",
+        };
+    }
+    if (value instanceof Object || Array.isArray(value)) {
+        const json = JSON.stringify(value);
+        return {
+            data: Buffer.from(json, "utf-8"),
+            contentType: "application/json",
+        };
+    }
+    throw new Error(`Value '${value}' cannot be converted to a Buffer.`);
+};
+/**
+ * @deprecated This function tests if the object provided is a Prismatic `DataPayload` object.
+ * A `DataPayload` object is an object with a `data` attribute, and optional `contentType` attribute.
+ *
+ * @param value The value to test
+ * @returns This function returns true if `value` is a DataPayload object, and false otherwise.
+ */
+const isData = (value) => isBufferDataPayload(value);
+/**
+ * @deprecated Many libraries for third-party API that handle binary files expect `Buffer` objects.
+ * This function helps to convert strings, Uint8Arrays, and Arrays to a data structure
+ * that has a Buffer and a string representing `contentType`.
+ *
+ * You can access the buffer like this:
+ *  `const { data, contentType } = util.types.toData(someData);`
+ *
+ * If `value` cannot be converted to a Buffer, an error will be thrown.
+ * @param value The string, Buffer, Uint8Array, or Array to convert to a Buffer.
+ * @returns This function returns an object with two keys: `data`, which is a `Buffer`, and `contentType`, which is a string.
+ */
+const toData = (value) => toBufferDataPayload(value);
+/**
+ * This function helps to format JSON examples for documentation.
+ * @param input An object to be JSONified.
+ * @returns This function returns a code block that can be used for documentation.
+ */
+const formatJsonExample = (input) => ["```json", JSON.stringify(input, undefined, 2), "```"].join("\n");
+/**
+ * This function converts a `value` to a string.
+ * If `value` is undefined or an empty string, an optional `defaultValue` can be returned.
+ *
+ * - `util.types.toString("Hello")` will return `"Hello"`.
+ * - `util.types.toString(5.5)` will return `"5.5"`.
+ * - `util.types.toString("", "Some default")` will return `"Some Default"`.
+ * - `util.types.toString(undefined)` will return `""`.
+ * @param value The value to convert to a string.
+ * @param defaultValue A default value to return if `value` is undefined or an empty string.
+ * @returns This function returns the stringified version fo `value`, or `defaultValue` in the case that `value` is undefined or an empty string.
+ */
+const toString = (value, defaultValue = "") => `${value !== null && value !== void 0 ? value : defaultValue}`;
+/**
+ * This function returns true if `value` resembles the shape of JSON, and false otherwise.
+ *
+ * - `isJSON(undefined) will return `false`
+ * - `isJSON(null) will return `true`
+ * - `isJSON("") will return `false`
+ * - `isJSON(5) will return `true`
+ * - `isJSON('{"name":"John", "age":30, "car":null}') will return `true`
+ * @param value The value to test against
+ * @returns This function returns a boolean, dependant on whether `value` can be parsed to JSON.
+ * */
+const isJSON = (value) => {
+    try {
+        JSON.parse(value);
+        return true;
+    }
+    catch (_a) {
+        return false;
+    }
+};
+exports.default = {
+    types: {
+        isBool,
+        toBool,
+        isInt,
+        toInt,
+        isNumber,
+        toNumber,
+        isBigInt,
+        toBigInt,
+        isDate,
+        toDate,
+        isUrl,
+        isBufferDataPayload,
+        toBufferDataPayload,
+        isData,
+        toData,
+        toString,
+        keyValPairListToObject,
+        isJSON,
+    },
+    docs: {
+        formatJsonExample,
+    },
+};