@prismatic-io/spectral 3.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 Prismatic LLC.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,55 @@
+# @prismatic-io/spectral
+
+This repository contains code for Prismatic's TypeScript library, `spectral`, which is used to build custom Prismatic components.
+
+## Using Spectral
+
+To install spectral, run:
+
+```bash
+npm install @prismatic-io/spectral
+```
+
+Please see our [documentation](https://prismatic.io/docs/custom-components/writing-custom-components) on writing and publishing custom components for Prismatic's platform.
+
+## What is Prismatic?
+
+Prismatic is the embedded integration platform for B2B software companies. It's the easiest way to build integrations and provide a first-class integration experience to your customers.
+
+Prismatic reduces integration effort and empowers every role with exactly what they need, so you can spend less time on integrations and more time on core product innovation.
+
+With Prismatic, you can:
+
+- Build reusable [integrations](https://prismatic.io/docs/integrations) in an intuitive low-code integration designer
+- Easily deploy customer-specific integration [instances](https://prismatic.io/docs/instances) with unique configurations and credentials
+- Run your integrations in a purpose-built environment
+- Provide better support with built-in [logging](https://prismatic.io/docs/logging) and [alerting](https://prismatic.io/docs/monitoring-and-alerting)
+- Embed a white-labeled customer integration portal with an [integration marketplace](https://prismatic.io/docs/integration-marketplace/) and customer self-service tools
+- Mold the platform to your product, industry, and the way you build software
+
+## Who uses Prismatic?
+
+Prismatic is for B2B (business-to-business) software companies, meaning software companies that provide applications used by businesses. It's a good fit for products/teams at any stage, including early stage SaaS, established SaaS, and legacy or on-prem systems.
+
+Many B2B software teams serve customers in niche vertical markets, and we designed Prismatic with that in mind. We provide powerful and flexible tools so you can build exactly the integrations your customers need, no matter who your customers are, no matter what systems you need to connect to, no matter how "non-standard" your integration scenario.
+
+## What kind of integrations can you build using Prismatic?
+
+Prismatic supports integrations ranging from simple and standard to complex, bespoke, and vertical-specific.
+Teams use it to build integrations between applications of all kinds, SaaS or legacy, with or without a modern API, regardless of protocol or data format.
+Here are some example use cases:
+
+- Use job data from your system to create invoices in your customers' ERP.
+- Import and process data from third-party forms that vary significantly from customer to customer.
+- Email activity summary reports with parameters and intervals defined on a per-customer basis.
+
+For information on the Prismatic platform, check out our [website](https://prismatic.io) and [docs](https://prismatic.io/docs).
+
+## Building Spectral Locally
+
+To build spectral locally, you'll need `yarn` and `node` installed.
+Run `yarn build` to build the package, or `yarn pack` to build a tarball that can be used in custom components for testing changes to spectral.
+
+## License
+
+This repository is [MIT licensed](./LICENSE).

package/dist/index.d.ts

@@ -0,0 +1,43 @@
+/**
+ * This module contains functions to help custom component
+ * authors create inputs, actions, and components that can
+ * be processed by the Prismatic API.
+ */
+/**
+ * Both component author-facing types and server types that
+ * the Prismatic API expects are imported here.
+ */
+import { ActionDefinition, InputFieldDefinition, PerformReturn, Inputs } from "./types";
+import { Component } from "./types/server-types";
+/**
+ * This function creates a component object that can be
+ * imported into the Prismatic API. For information on using
+ * this function to write custom components, see
+ * https://prismatic.io/docs/custom-components/writing-custom-components/#exporting-a-component.
+ * @param definition A ComponentDefinition type object, including display infromation, unique key, authorization information, and a set of actions the component implements.
+ * @returns This function returns a component object that has the shape the Prismatic API expects.
+ */
+export declare const component: <T extends boolean>(definition: Omit<Component<T>, "actions"> & {
+    actions: Record<string, ActionDefinition<any, boolean, PerformReturn<boolean, any>>>;
+}) => Component<T>;
+/**
+ * This function creates an action object that can be referenced
+ * by a custom component. It helps ensure that the shape of the
+ * action object conforms to what the Prismatic API expects.
+ * For information on writing custom component actions, see
+ * https://prismatic.io/docs/custom-components/writing-custom-components/#writing-actions.
+ * @param definition An ActionDefinition type object that includes UI display information, a function to perform when the action is invoked, and a an object containing inputs for the perform function.
+ * @returns This function validates the shape of the `definition` object provided, and returns the same action object.
+ */
+export declare const action: <T extends Inputs, AllowsBranching extends boolean, ReturnData extends PerformReturn<AllowsBranching, unknown>>(definition: ActionDefinition<T, AllowsBranching, ReturnData>) => ActionDefinition<T, AllowsBranching, ReturnData>;
+/**
+ * For information and examples on how to write inputs
+ * for custom component actions, see
+ * https://prismatic.io/docs/custom-components/writing-custom-components/#adding-inputs.
+ * @param definition An InputFieldDefinition object that describes the type of an input for a custom component action, and information on how it should be displayed in the Prismatic WebApp.
+ * @returns This function validates the shape of the `definition` object provided, and returns the same input object.
+ */
+export declare const input: <T extends InputFieldDefinition>(definition: T) => T;
+export { default as util } from "./util";
+export * from "./types";
+export { default as testing } from "./testing";

package/dist/index.js

@@ -0,0 +1,73 @@
+"use strict";
+/**
+ * This module contains functions to help custom component
+ * authors create inputs, actions, and components that can
+ * be processed by the Prismatic API.
+ */
+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);
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.testing = exports.util = exports.input = exports.action = exports.component = void 0;
+/**
+ * This is a helper function for component() to convert an
+ * action defined in TypeScript into an action object that
+ * Prismatic's API can process.
+ * @param actionKey The unique identifier of an action.
+ * @param action The action definition, including its inputs, perform function, and app display information.
+ * @returns This function returns an action object that has the shape the Prismatic API expects.
+ */
+const convertAction = (actionKey, action) => {
+    var _a;
+    const items = Object.entries((_a = action.inputs) !== null && _a !== void 0 ? _a : {});
+    const inputDefinitions = items.map(([key, value]) => (Object.assign({ key }, (typeof value === "object" ? value : {}))));
+    return Object.assign(Object.assign({}, action), { key: actionKey, inputs: inputDefinitions, perform: action.perform, examplePayload: action.examplePayload });
+};
+/**
+ * This function creates a component object that can be
+ * imported into the Prismatic API. For information on using
+ * this function to write custom components, see
+ * https://prismatic.io/docs/custom-components/writing-custom-components/#exporting-a-component.
+ * @param definition A ComponentDefinition type object, including display infromation, unique key, authorization information, and a set of actions the component implements.
+ * @returns This function returns a component object that has the shape the Prismatic API expects.
+ */
+const component = (definition) => (Object.assign(Object.assign({ version: "placeholder" }, definition), { documentationUrl: definition.documentationUrl || null, actions: Object.fromEntries(Object.entries(definition.actions).map(([actionKey, action]) => [
+        actionKey,
+        convertAction(actionKey, action),
+    ])) }));
+exports.component = component;
+/**
+ * This function creates an action object that can be referenced
+ * by a custom component. It helps ensure that the shape of the
+ * action object conforms to what the Prismatic API expects.
+ * For information on writing custom component actions, see
+ * https://prismatic.io/docs/custom-components/writing-custom-components/#writing-actions.
+ * @param definition An ActionDefinition type object that includes UI display information, a function to perform when the action is invoked, and a an object containing inputs for the perform function.
+ * @returns This function validates the shape of the `definition` object provided, and returns the same action object.
+ */
+const action = (definition) => definition;
+exports.action = action;
+/**
+ * For information and examples on how to write inputs
+ * for custom component actions, see
+ * https://prismatic.io/docs/custom-components/writing-custom-components/#adding-inputs.
+ * @param definition An InputFieldDefinition object that describes the type of an input for a custom component action, and information on how it should be displayed in the Prismatic WebApp.
+ * @returns This function validates the shape of the `definition` object provided, and returns the same input object.
+ */
+const input = (definition) => definition;
+exports.input = input;
+var util_1 = require("./util");
+Object.defineProperty(exports, "util", { enumerable: true, get: function () { return __importDefault(util_1).default; } });
+__exportStar(require("./types"), exports);
+var testing_1 = require("./testing");
+Object.defineProperty(exports, "testing", { enumerable: true, get: function () { return __importDefault(testing_1).default; } });

package/dist/testing.d.ts

@@ -0,0 +1,72 @@
+/**
+ * This module provides functions to help developers unit
+ * test custom components prior to publishing them. For
+ * information on unit testing, check out our docs:
+ * https://prismatic.io/docs/custom-components/writing-custom-components/#testing-a-component
+ */
+/** */
+import { ActionContext, ActionLogger, ActionDefinition, ActionInputParameters, Credential, BasicCredential, ApiKeyCredential, ApiKeySecretCredential, PrivateKeyCredential, OAuth2Credential, PerformReturn, AuthorizationMethod, Inputs } from "./types";
+/**
+ * Get an array of available authorization methods that a custom component can use.
+ * @param except Return authorization methods _except for_ those in this array.
+ * @returns This function returns an array of available authorization methods.
+ */
+export declare const getAuthorizationMethods: (except?: ("basic" | "api_key" | "api_key_secret" | "private_key" | "oauth2" | "oauth2_client_credentials")[] | undefined) => AuthorizationMethod[];
+/** Utility functions to generate the different types of Credentials for testing. */
+export declare const credentials: {
+    /** Return a BasicCredential assembled from provided username and password. */
+    basic: (username: string, password: string) => BasicCredential;
+    /** Return a ApiKeyCredential assembled from provided key. */
+    apiKey: (key: string) => ApiKeyCredential;
+    /** Return a ApiKeySecretCredential assembled from provided key and secret. */
+    apiKeySecret: (key: string, secret: string) => ApiKeySecretCredential;
+    /** Return a PrivateKeyCredential assembled from provided username and privateKey. */
+    privateKey: (username: string, privateKey: string) => PrivateKeyCredential;
+    /** Return a OAuth2Credential assembled from provided token and optional redirectUri. */
+    oauth2: (token: string, redirectUri?: string, tokenUri?: string, clientId?: string, clientSecret?: string, headers?: {}) => OAuth2Credential;
+    /** Return a OAuth2Credential assembled from provided token. */
+    oauth2ClientCredentials: (token: string, redirectUri?: string, tokenUri?: string, clientId?: string, clientSecret?: string, headers?: {}) => OAuth2Credential;
+    /** Returns an arbitrary Credential using method. Generally used for testing negative support cases. */
+    generate: (method: AuthorizationMethod) => Credential;
+};
+/**
+ * Pre-built mock of ActionLogger. Suitable for asserting logs are created as expected.
+ * See https://prismatic.io/docs/custom-components/writing-custom-components/#verifying-correct-logging-in-action-tests for information on testing correct logging behavior in your custom component.
+ */
+export declare const loggerMock: () => ActionLogger;
+/**
+ * The type of data returned by an `invoke()` function used for unit testing component actions.
+ */
+interface InvokeReturn<ReturnData> {
+    result: ReturnData;
+    loggerMock: ActionLogger;
+}
+/**
+ * Invokes specified ActionDefinition perform function using supplied params
+ * and optional context. Accepts a generic type matching PerformReturn as a convenience
+ * to avoid extra casting within test methods. Returns an InvokeResult containing both the
+ * action result and a mock logger for asserting logging.
+ */
+export declare const invoke: <T extends Inputs, AllowsBranching extends boolean, ReturnData extends PerformReturn<AllowsBranching, unknown>>(actionBase: ActionDefinition<T, AllowsBranching, ReturnData> | Record<string, ActionDefinition<T, AllowsBranching, ReturnData>>, params: ActionInputParameters<T>, context?: Partial<ActionContext> | undefined) => Promise<InvokeReturn<ReturnData>>;
+declare const _default: {
+    invoke: <T extends Inputs, AllowsBranching extends boolean, ReturnData extends PerformReturn<AllowsBranching, unknown>>(actionBase: ActionDefinition<T, AllowsBranching, ReturnData> | Record<string, ActionDefinition<T, AllowsBranching, ReturnData>>, params: ActionInputParameters<T>, context?: Partial<ActionContext> | undefined) => Promise<InvokeReturn<ReturnData>>;
+    loggerMock: () => ActionLogger;
+    getAuthorizationMethods: (except?: ("basic" | "api_key" | "api_key_secret" | "private_key" | "oauth2" | "oauth2_client_credentials")[] | undefined) => ("basic" | "api_key" | "api_key_secret" | "private_key" | "oauth2" | "oauth2_client_credentials")[];
+    credentials: {
+        /** Return a BasicCredential assembled from provided username and password. */
+        basic: (username: string, password: string) => BasicCredential;
+        /** Return a ApiKeyCredential assembled from provided key. */
+        apiKey: (key: string) => ApiKeyCredential;
+        /** Return a ApiKeySecretCredential assembled from provided key and secret. */
+        apiKeySecret: (key: string, secret: string) => ApiKeySecretCredential;
+        /** Return a PrivateKeyCredential assembled from provided username and privateKey. */
+        privateKey: (username: string, privateKey: string) => PrivateKeyCredential;
+        /** Return a OAuth2Credential assembled from provided token and optional redirectUri. */
+        oauth2: (token: string, redirectUri?: string, tokenUri?: string, clientId?: string, clientSecret?: string, headers?: {}) => OAuth2Credential;
+        /** Return a OAuth2Credential assembled from provided token. */
+        oauth2ClientCredentials: (token: string, redirectUri?: string, tokenUri?: string, clientId?: string, clientSecret?: string, headers?: {}) => OAuth2Credential;
+        /** Returns an arbitrary Credential using method. Generally used for testing negative support cases. */
+        generate: (method: "basic" | "api_key" | "api_key_secret" | "private_key" | "oauth2" | "oauth2_client_credentials") => Credential;
+    };
+};
+export default _default;

package/dist/testing.js

@@ -0,0 +1,130 @@
+"use strict";
+/**
+ * This module provides functions to help developers unit
+ * test custom components prior to publishing them. For
+ * information on unit testing, check out our docs:
+ * https://prismatic.io/docs/custom-components/writing-custom-components/#testing-a-component
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.invoke = exports.loggerMock = exports.credentials = exports.getAuthorizationMethods = void 0;
+/** */
+const types_1 = require("./types");
+const jest_mock_1 = require("jest-mock");
+/**
+ * Get an array of available authorization methods that a custom component can use.
+ * @param except Return authorization methods _except for_ those in this array.
+ * @returns This function returns an array of available authorization methods.
+ */
+const getAuthorizationMethods = (except) => {
+    if (except === undefined) {
+        return types_1.AvailableAuthorizationMethods;
+    }
+    return types_1.AvailableAuthorizationMethods.filter((m) => !except.includes(m));
+};
+exports.getAuthorizationMethods = getAuthorizationMethods;
+/** Utility functions to generate the different types of Credentials for testing. */
+exports.credentials = {
+    /** Return a BasicCredential assembled from provided username and password. */
+    basic: (username, password) => ({
+        authorizationMethod: "basic",
+        fields: {
+            username,
+            password,
+        },
+    }),
+    /** Return a ApiKeyCredential assembled from provided key. */
+    apiKey: (key) => ({
+        authorizationMethod: "api_key",
+        fields: { api_key: key },
+    }),
+    /** Return a ApiKeySecretCredential assembled from provided key and secret. */
+    apiKeySecret: (key, secret) => ({
+        authorizationMethod: "api_key_secret",
+        fields: {
+            api_key: key,
+            api_secret: secret,
+        },
+    }),
+    /** Return a PrivateKeyCredential assembled from provided username and privateKey. */
+    privateKey: (username, privateKey) => ({
+        authorizationMethod: "private_key",
+        fields: {
+            username,
+            private_key: privateKey,
+        },
+    }),
+    /** Return a OAuth2Credential assembled from provided token and optional redirectUri. */
+    oauth2: (token, redirectUri = "", tokenUri = "", clientId = "", clientSecret = "", headers = {}) => ({
+        authorizationMethod: "oauth2",
+        redirectUri,
+        fields: {
+            client_id: clientId,
+            client_secret: clientSecret,
+            token_uri: tokenUri,
+            headers,
+        },
+        token: { access_token: token, token_type: "bearer" },
+        context: {},
+    }),
+    /** Return a OAuth2Credential assembled from provided token. */
+    oauth2ClientCredentials: (token, redirectUri = "", tokenUri = "", clientId = "", clientSecret = "", headers = {}) => ({
+        authorizationMethod: "oauth2_client_credentials",
+        redirectUri: redirectUri,
+        fields: {
+            client_id: clientId,
+            client_secret: clientSecret,
+            token_uri: tokenUri,
+            headers,
+        },
+        token: { access_token: token, token_type: "bearer" },
+        context: {},
+    }),
+    /** Returns an arbitrary Credential using method. Generally used for testing negative support cases. */
+    generate: (method) => ({
+        authorizationMethod: method,
+        fields: {},
+    }),
+};
+/**
+ * Pre-built mock of ActionLogger. Suitable for asserting logs are created as expected.
+ * See https://prismatic.io/docs/custom-components/writing-custom-components/#verifying-correct-logging-in-action-tests for information on testing correct logging behavior in your custom component.
+ */
+const loggerMock = () => ({
+    debug: jest_mock_1.spyOn(console, "debug"),
+    info: jest_mock_1.spyOn(console, "info"),
+    log: jest_mock_1.spyOn(console, "log"),
+    warn: jest_mock_1.spyOn(console, "warn"),
+    error: jest_mock_1.spyOn(console, "error"),
+});
+exports.loggerMock = loggerMock;
+/**
+ * Invokes specified ActionDefinition perform function using supplied params
+ * and optional context. Accepts a generic type matching PerformReturn as a convenience
+ * to avoid extra casting within test methods. Returns an InvokeResult containing both the
+ * action result and a mock logger for asserting logging.
+ */
+const invoke = (actionBase, params, context) => __awaiter(void 0, void 0, void 0, function* () {
+    const action = (actionBase.perform ? actionBase : Object.values(actionBase)[0]);
+    const realizedContext = Object.assign({ credential: undefined, logger: exports.loggerMock(), instanceState: {}, stepId: "mockStepId" }, context);
+    const result = yield action.perform(realizedContext, params);
+    return {
+        result,
+        loggerMock: realizedContext.logger,
+    };
+});
+exports.invoke = invoke;
+exports.default = {
+    invoke: exports.invoke,
+    loggerMock: exports.loggerMock,
+    getAuthorizationMethods: exports.getAuthorizationMethods,
+    credentials: exports.credentials,
+};

package/dist/types/ActionDefinition.d.ts

@@ -0,0 +1,25 @@
+import { PerformReturn, ActionDisplayDefinition, ActionPerformFunction, AuthorizationDefinition, Inputs } from ".";
+/**
+ * ActionDefinition is the type of the object that is passed in to `action` function to
+ * define a component action.
+ */
+export interface ActionDefinition<T extends Inputs, AllowsBranching extends boolean, ReturnData extends PerformReturn<AllowsBranching, unknown>> {
+    /** Defines how the Action is displayed in the Prismatic interface. */
+    display: ActionDisplayDefinition;
+    /** Function to perform when this Action is invoked. */
+    perform: ActionPerformFunction<T, AllowsBranching, ReturnData>;
+    /** InputFields to present in the Prismatic interface for configuration of this Action. */
+    inputs: T;
+    /** 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?: AllowsBranching;
+    /** 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?: ReturnData;
+}

package/dist/types/ActionDefinition.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/types/ActionInputParameters.d.ts

@@ -0,0 +1,24 @@
+import { InputFieldDefinition, Inputs, InputFieldTypeMap } from ".";
+/**
+ * Collection of input parameters.
+ * Inputs can be static values, references to config variables, or
+ * references to previou steps' outputs.
+ */
+export declare type ActionInputParameters<T extends Inputs> = T extends Record<string, InputFieldDefinition> ? {
+    [K in keyof T]: ExtractValue<T[K]>;
+} : never;
+export declare type ExtractValue<TValue extends InputFieldDefinition> = MapCollectionValues<InputFieldTypeMap[TValue["type"]], TValue["collection"]>;
+export declare type MapCollectionValues<TValue, TCollection extends InputFieldDefinition["collection"] | undefined> = TCollection extends "keyvaluelist" ? KeyValuePair<TValue>[] | undefined : TCollection extends "valuelist" ? TValue[] | undefined : TValue;
+/**
+ * KeyValuePair input parameter type.
+ * This allows users to input multiple keys / values as an input.
+ * To see an example of how this can be used, see the `tagging` input
+ * of the `putObject` action of the AWS S3 component:
+ * https://github.com/prismatic-io/examples/blob/main/components/aws-s3/src/actions.ts
+ */
+export interface KeyValuePair<V = unknown> {
+    /** Key of the KeyValuePair */
+    key: string;
+    /** Value of the KeyValuePair */
+    value: V;
+}