@prismatic-io/spectral 10.17.2 → 10.18.2

package/dist/index.js

@@ -22,18 +22,34 @@ 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.componentManifests = exports.oauth2Connection = exports.onPremConnection = exports.connection = exports.input = exports.dataSource = exports.pollingTrigger = exports.trigger = exports.action = exports.component = exports.componentManifest = exports.organizationActivatedConnection = exports.customerActivatedConnection = exports.connectionConfigVar = exports.dataSourceConfigVar = exports.configVar = exports.configPage = exports.flow = exports.integration = void 0;
+exports.util = exports.testing = exports.componentManifests = exports.oauth2Connection = exports.onPremConnection = exports.connection = exports.input = exports.dataSource = exports.pollingTrigger = exports.trigger = exports.action = exports.component = exports.componentManifest = exports.organizationActivatedConnection = exports.customerActivatedConnection = exports.connectionConfigVar = exports.dataSourceConfigVar = exports.configVar = exports.configPage = exports.flow = exports.integration = void 0;
+const serverTypes_1 = require("./serverTypes");
 const convertComponent_1 = require("./serverTypes/convertComponent");
 const convertIntegration_1 = require("./serverTypes/convertIntegration");
-const serverTypes_1 = require("./serverTypes");
 /**
  * This function creates a code-native integration object that can be
- * imported into Prismatic. For information on using this function to
- * write code-native integrations, see
- * https://prismatic.io/docs/integrations/code-native/.
+ * imported into Prismatic.
  *
  * @param definition An IntegrationDefinition type object.
  * @returns This function returns an integration object that has the shape the Prismatic API expects.
+ * @see {@link https://prismatic.io/docs/integrations/code-native/ | Code-Native Integrations}
+ * @example
+ * import { integration } from "@prismatic-io/spectral";
+ * import flows from "./flows";
+ * import { configPages } from "./configPages";
+ * import { componentRegistry } from "./componentRegistry";
+ *
+ * export default integration({
+ *   name: "Acme Integration",
+ *   description: "Syncs data between Acme and your system",
+ *   category: "Communication",
+ *   labels: ["chat", "beta"],
+ *   iconPath: "icon.png",
+ *   version: "1.0.0",
+ *   flows,
+ *   configPages,
+ *   componentRegistry,
+ * });
  */
 const integration = (definition) => {
     var _a;
@@ -48,63 +64,210 @@ const integration = (definition) => {
 exports.integration = integration;
 /**
  * This function creates a flow object for use in code-native integrations.
- * For information on writing code-native flows, see
- * https://prismatic.io/docs/integrations/code-native/flows/.
  *
  * @param definition A Flow type object.
  * @returns This function returns a flow object that has the shape the Prismatic API expects.
+ * @see {@link https://prismatic.io/docs/integrations/code-native/flows/ | Code-Native Flows}
+ * @example
+ * // A webhook-triggered flow
+ * import { flow } from "@prismatic-io/spectral";
+ *
+ * export const myFlow = flow({
+ *   name: "Process Webhook",
+ *   stableKey: "process-webhook",
+ *   description: "Receives and processes incoming webhooks",
+ *   onTrigger: async (context, payload, params) => {
+ *     return Promise.resolve({ payload });
+ *   },
+ *   onExecution: async (context, params) => {
+ *     const { logger, configVars } = context;
+ *     const triggerData = params.onTrigger.results;
+ *     logger.info("Processing webhook payload");
+ *     return Promise.resolve({ data: triggerData });
+ *   },
+ * });
+ *
+ * @example
+ * // A scheduled flow with cron expression
+ * import { flow } from "@prismatic-io/spectral";
+ *
+ * export const scheduledSync = flow({
+ *   name: "Nightly Sync",
+ *   stableKey: "nightly-sync",
+ *   description: "Syncs data every night at midnight",
+ *   schedule: { value: "0 0 * * *", timezone: "America/Chicago" },
+ *   onExecution: async (context, params) => {
+ *     context.logger.info(`Sync started at ${new Date().toISOString()}`);
+ *     return Promise.resolve({ data: null });
+ *   },
+ * });
  */
 const flow = (definition) => definition;
 exports.flow = flow;
 /**
  * This function creates a config wizard page object for use in code-native
- * integrations. For information on code-native config wizards, see
- * https://prismatic.io/docs/integrations/code-native/config-wizard/.
+ * integrations.
  *
  * @param definition A Config Page type object.
  * @returns This function returns a config page object that has the shape the Prismatic API expects.
+ * @see {@link https://prismatic.io/docs/integrations/code-native/config-wizard/ | Code-Native Config Wizard}
+ * @example
+ * import { configPage, connectionConfigVar, configVar } from "@prismatic-io/spectral";
+ *
+ * export const configPages = {
+ *   Connections: configPage({
+ *     tagline: "Set up your API connections",
+ *     elements: {
+ *       "Acme Connection": connectionConfigVar({
+ *         stableKey: "acme-connection",
+ *         dataType: "connection",
+ *         inputs: {
+ *           apiKey: { label: "API Key", type: "password", required: true },
+ *           baseUrl: { label: "Base URL", type: "string", required: true },
+ *         },
+ *       }),
+ *     },
+ *   }),
+ *   Configuration: configPage({
+ *     tagline: "Configure sync settings",
+ *     elements: {
+ *       "Sync Interval": configVar({
+ *         stableKey: "sync-interval",
+ *         dataType: "picklist",
+ *         pickList: ["hourly", "daily", "weekly"],
+ *         defaultValue: "daily",
+ *       }),
+ *     },
+ *   }),
+ * };
  */
 const configPage = (definition) => definition;
 exports.configPage = configPage;
 /**
  * This function creates a config variable object for code-native integrations.
- * For information on writing code-native integrations, see
- * https://prismatic.io/docs/integrations/code-native/config-wizard/#other-config-variable-types-in-code-native-integrations.
  *
  * @param definition A Config Var type object.
  * @returns This function returns a standard config var object that has the shape the Prismatic API expects.
+ * @see {@link https://prismatic.io/docs/integrations/code-native/config-wizard/#other-config-variable-types-in-code-native-integrations | Config Variable Types}
+ * @example
+ * import { configVar } from "@prismatic-io/spectral";
+ *
+ * // String config variable
+ * const endpoint = configVar({
+ *   stableKey: "api-endpoint",
+ *   dataType: "string",
+ *   defaultValue: "https://api.example.com",
+ *   description: "The base URL of the API",
+ * });
+ *
+ * @example
+ * import { configVar } from "@prismatic-io/spectral";
+ *
+ * // Picklist config variable
+ * const region = configVar({
+ *   stableKey: "region",
+ *   dataType: "picklist",
+ *   pickList: ["us-east-1", "us-west-2", "eu-west-1"],
+ *   defaultValue: "us-east-1",
+ *   description: "AWS region to use",
+ * });
+ *
+ * @example
+ * import { configVar } from "@prismatic-io/spectral";
+ *
+ * // Boolean config variable
+ * const enableDebug = configVar({
+ *   stableKey: "enable-debug",
+ *   dataType: "boolean",
+ *   defaultValue: false,
+ *   description: "Enable debug logging",
+ * });
+ *
+ * @example
+ * import { configVar } from "@prismatic-io/spectral";
+ *
+ * // Schedule config variable
+ * const syncSchedule = configVar({
+ *   stableKey: "sync-schedule",
+ *   dataType: "schedule",
+ *   description: "When to run the sync",
+ *   timeZone: "America/Chicago",
+ * });
  */
 const configVar = (definition) => definition;
 exports.configVar = configVar;
 /**
  * This function creates a data source-backed config variable for code-native
- * integrations. For information on code-native data sources, see
- * https://prismatic.io/docs/integrations/code-native/config-wizard/#data-sources-is-code-native-integrations.
+ * integrations.
  *
  * @param definition A Data Source Config Var type object.
  * @returns This function returns a data source config var object that has the shape the Prismatic API expects.
+ * @see {@link https://prismatic.io/docs/integrations/code-native/config-wizard/#data-sources-is-code-native-integrations | Data Sources in Code-Native}
+ * @example
+ * import { dataSourceConfigVar } from "@prismatic-io/spectral";
+ *
+ * const selectRepository = dataSourceConfigVar({
+ *   stableKey: "select-repo",
+ *   dataSourceType: "picklist",
+ *   description: "Choose a repository from GitHub",
+ *   perform: async (context, params) => {
+ *     // Fetch repos from an API and return them as picklist options
+ *     return { result: ["repo-1", "repo-2", "repo-3"] };
+ *   },
+ * });
  */
 const dataSourceConfigVar = (definition) => definition;
 exports.dataSourceConfigVar = dataSourceConfigVar;
 /**
  * This function creates a connection config variable for code-native
- * integrations. For information on writing code-native integrations, see
- * https://prismatic.io/docs/integrations/code-native/config-wizard/#connections-in-code-native-integrations.
+ * integrations.
  *
  * @param definition A Connection Config Var type object.
  * @returns This function returns a connection config var object that has the shape the Prismatic API expects.
+ * @see {@link https://prismatic.io/docs/integrations/code-native/config-wizard/#connections-in-code-native-integrations | Connections in Code-Native}
+ * @example
+ * import { connectionConfigVar } from "@prismatic-io/spectral";
+ * import { acmeConnection } from "./connections";
+ *
+ * const myConnection = connectionConfigVar({
+ *   stableKey: "acme-connection",
+ *   ...acmeConnection,
+ * });
+ *
+ * @example
+ * import { connectionConfigVar } from "@prismatic-io/spectral";
+ *
+ * // Inline connection definition
+ * const myApiConnection = connectionConfigVar({
+ *   stableKey: "my-api-connection",
+ *   dataType: "connection",
+ *   inputs: {
+ *     apiKey: { label: "API Key", type: "password", required: true },
+ *     baseUrl: {
+ *       label: "Base URL",
+ *       type: "string",
+ *       required: true,
+ *       default: "https://api.example.com",
+ *     },
+ *   },
+ * });
  */
 const connectionConfigVar = (definition) => definition;
 exports.connectionConfigVar = connectionConfigVar;
 /**
  * This function creates a customer-activated connection for code-native
- * integrations. For information on writing code-native integrations, see
- * https://prismatic.io/docs/integrations/code-native/.
- * For information on customer-activated connections, see
- * https://prismatic.io/docs/integrations/connections/integration-agnostic-connections/customer-activated/.
+ * integrations. Customer-activated connections are configured by end-users
+ * and can be shared across multiple integrations.
  *
  * @param definition A Customer-Activated Connection Config Var type object.
  * @returns This function returns a connection config var object that has the shape the Prismatic API expects.
+ * @see {@link https://prismatic.io/docs/integrations/connections/integration-agnostic-connections/customer-activated/ | Customer-Activated Connections}
+ * @example
+ * import { customerActivatedConnection } from "@prismatic-io/spectral";
+ *
+ * const sharedSlackConnection = customerActivatedConnection({
+ *   stableKey: "shared-slack-connection",
+ * });
  */
 const customerActivatedConnection = (definition) => {
     return Object.assign(Object.assign({}, definition), { dataType: "connection" });
@@ -112,35 +275,73 @@ const customerActivatedConnection = (definition) => {
 exports.customerActivatedConnection = customerActivatedConnection;
 /**
  * This function creates an org-activated connection for code-native
- * integrations. For information on writing code-native integrations, see
- * https://prismatic.io/docs/integrations/code-native/.
- * For information on customer-activated connections, see
- * https://prismatic.io/docs/integrations/connections/integration-agnostic-connections/org-activated-customer/.
+ * integrations. Org-activated connections are configured once by the
+ * organization and shared across all customer instances.
  *
  * @param definition An Organization-Activated Connection Config Var type object.
  * @returns This function returns a connection config var object that has the shape the Prismatic API expects.
+ * @see {@link https://prismatic.io/docs/integrations/connections/integration-agnostic-connections/org-activated-customer/ | Org-Activated Connections}
+ * @example
+ * import { organizationActivatedConnection } from "@prismatic-io/spectral";
+ *
+ * const orgSlackConnection = organizationActivatedConnection({
+ *   stableKey: "org-slack-connection",
+ * });
  */
 const organizationActivatedConnection = (definition) => {
     return Object.assign(Object.assign({}, definition), { dataType: "connection" });
 };
 exports.organizationActivatedConnection = organizationActivatedConnection;
 /**
- * Generate a manifest of components that this code-native integration relies on. See
- * https://prismatic.io/docs/integrations/code-native/existing-components/
+ * Generate a manifest of components that this code-native integration relies on.
+ * Component manifests allow your code-native integration to reference actions,
+ * triggers, connections, and data sources from published Prismatic components.
  *
  * @param definition A Component Manifest type object.
  * @returns This function returns a component manifest object that has the shape the Prismatic API expects.
+ * @see {@link https://prismatic.io/docs/integrations/code-native/existing-components/ | Using Existing Components}
+ * @example
+ * import { componentManifest } from "@prismatic-io/spectral";
+ *
+ * const slack = componentManifest({
+ *   key: "slack",
+ *   public: true,
+ *   actions: {
+ *     postMessage: {
+ *       inputs: {
+ *         message: { label: "Message" },
+ *         channelName: { label: "Channel Name" },
+ *       },
+ *     },
+ *   },
+ * });
  */
 const componentManifest = (definition) => definition;
 exports.componentManifest = componentManifest;
 /**
  * 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-connectors/.
+ * imported into the Prismatic API.
  *
  * @param definition A ComponentDefinition type object, including display information, unique key, and a set of actions the component implements.
  * @returns This function returns a component object that has the shape the Prismatic API expects.
+ * @see {@link https://prismatic.io/docs/custom-connectors/ | Custom Connectors}
+ * @example
+ * import { component } from "@prismatic-io/spectral";
+ * import actions from "./actions";
+ * import triggers from "./triggers";
+ * import connections from "./connections";
+ *
+ * export default component({
+ *   key: "acme-connector",
+ *   display: {
+ *     label: "Acme",
+ *     description: "Interact with Acme's API",
+ *     iconPath: "icon.png",
+ *   },
+ *   actions,
+ *   triggers,
+ *   connections,
+ * });
  */
 const component = (definition) => (0, convertComponent_1.convertComponent)(definition);
 exports.component = component;
@@ -148,11 +349,35 @@ 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-connectors/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.
+ * @param definition An ActionDefinition type object that includes UI display information, a function to perform when the action is invoked, and 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.
+ * @see {@link https://prismatic.io/docs/custom-connectors/actions/ | Writing Custom Actions}
+ * @example
+ * import { action, input, util } from "@prismatic-io/spectral";
+ *
+ * const listItems = action({
+ *   display: {
+ *     label: "List Items",
+ *     description: "Retrieve a list of items from Acme",
+ *   },
+ *   inputs: {
+ *     connection: input({ label: "Connection", type: "connection", required: true }),
+ *     limit: input({
+ *       label: "Limit",
+ *       type: "string",
+ *       required: false,
+ *       default: "100",
+ *       comments: "Maximum number of items to return",
+ *     }),
+ *   },
+ *   perform: async (context, { connection, limit }) => {
+ *     const maxItems = util.types.toInt(limit, 100);
+ *     context.logger.info(`Fetching up to ${maxItems} items`);
+ *     // Make API call using connection...
+ *     return { data: { items: [] } };
+ *   },
+ * });
  */
 const action = (definition) => definition;
 exports.action = action;
@@ -160,21 +385,78 @@ exports.action = action;
  * This function creates a trigger object that can be referenced
  * by a custom component. It helps ensure that the shape of the
  * trigger object conforms to what the Prismatic API expects.
- * For information on writing custom component triggers, see
- * https://prismatic.io/docs/custom-connectors/triggers/.
  *
- * @param definition A TriggerDefinition type object that includes UI display information, a function to perform when the trigger is invoked, and a an object containing inputs for the perform function.
+ * @param definition A TriggerDefinition type object that includes UI display information, a function to perform when the trigger is invoked, and an object containing inputs for the perform function.
  * @returns This function validates the shape of the `definition` object provided, and returns the same trigger object.
+ * @see {@link https://prismatic.io/docs/custom-connectors/triggers/ | Writing Custom Triggers}
+ * @example
+ * import { trigger, input } from "@prismatic-io/spectral";
+ * import { HttpResponse } from "@prismatic-io/spectral";
+ *
+ * const webhookTrigger = trigger({
+ *   display: {
+ *     label: "Acme Webhook",
+ *     description: "Receives webhooks from Acme",
+ *   },
+ *   inputs: {
+ *     secret: input({
+ *       label: "Signing Secret",
+ *       type: "password",
+ *       required: true,
+ *       comments: "Used to verify webhook signatures",
+ *     }),
+ *   },
+ *   scheduleSupport: "invalid",
+ *   synchronousResponseSupport: "valid",
+ *   perform: async (context, payload, { secret }) => {
+ *     // Validate and process the incoming webhook
+ *     const response: HttpResponse = {
+ *       statusCode: 200,
+ *       contentType: "application/json",
+ *       body: JSON.stringify({ received: true }),
+ *     };
+ *     return Promise.resolve({
+ *       payload,
+ *       response,
+ *     });
+ *   },
+ * });
  */
 const trigger = (definition) => definition;
 exports.trigger = trigger;
 /**
  * This function creates a polling trigger object that can be referenced
- * by a custom component. See
- * https://prismatic.io/docs/custom-connectors/triggers/#app-event-polling-triggers
+ * by a custom component. A polling trigger runs on a schedule and uses
+ * `context.polling` to track state between invocations, enabling detection
+ * of new or changed records.
  *
- * @param definition A PollingTriggerDefinition is similar to a TriggerDefinition, except it requires a pollAction instead of a perform. The pollAction, which can be any action defined in the component, will be polled on the defined schedule.
+ * @param definition A PollingTriggerDefinition, similar to a TriggerDefinition, except it requires a pollAction instead of a perform. The pollAction, which can be any action defined in the component, will be polled on the defined schedule.
+ * @see {@link https://prismatic.io/docs/custom-connectors/triggers/#app-event-polling-triggers | Polling Triggers}
  * @returns This function validates the shape of the `definition` object provided, and returns the same polling trigger object.
+ * @example
+ * import { pollingTrigger, input } from "@prismatic-io/spectral";
+ *
+ * const newRecordsTrigger = pollingTrigger({
+ *   display: {
+ *     label: "New Records",
+ *     description: "Triggers when new records are detected",
+ *   },
+ *   inputs: {
+ *     connection: input({ label: "Connection", type: "connection", required: true }),
+ *   },
+ *   perform: async (context, payload, params) => {
+ *     const lastCursor = context.polling.getState()["cursor"] ?? "";
+ *     // Fetch records since lastCursor...
+ *     const newRecords = []; // results from API
+ *     context.polling.setState({ cursor: "new-cursor-value" });
+ *     return Promise.resolve({
+ *       payload: {
+ *         ...payload,
+ *         body: { data: newRecords },
+ *       },
+ *     });
+ *   },
+ * });
  */
 const pollingTrigger = (definition) => {
     return Object.assign(Object.assign({}, definition), { triggerType: "polling" });
@@ -184,59 +466,267 @@ exports.pollingTrigger = pollingTrigger;
  * This function creates a data source object that can be referenced
  * by a custom component. It helps ensure that the shape of the
  * data source object conforms to what the Prismatic API expects.
- * For information on writing custom component data sources, see
- * https://prismatic.io/docs/custom-connectors/data-sources/.
  *
- * @param definition A DataSourceDefinition type object that includes UI display information, a function to perform when the data source is invoked, and a an object containing inputs for the perform function.
+ * @param definition A DataSourceDefinition type object that includes UI display information, a function to perform when the data source is invoked, and an object containing inputs for the perform function.
  * @returns This function validates the shape of the `definition` object provided, and returns the same data source object.
+ * @see {@link https://prismatic.io/docs/custom-connectors/data-sources/ | Writing Custom Data Sources}
+ * @example
+ * import { dataSource, input } from "@prismatic-io/spectral";
+ *
+ * const selectChannel = dataSource({
+ *   display: {
+ *     label: "Select Channel",
+ *     description: "Fetches a list of channels from the API",
+ *   },
+ *   dataSourceType: "picklist",
+ *   inputs: {
+ *     connection: input({ label: "Connection", type: "connection", required: true }),
+ *   },
+ *   perform: async (context, { connection }) => {
+ *     // Fetch channels from API using the connection...
+ *     return {
+ *       result: [
+ *         { label: "General", value: "C123" },
+ *         { label: "Engineering", value: "C456" },
+ *       ],
+ *     };
+ *   },
+ * });
  */
 const dataSource = (definition) => definition;
 exports.dataSource = dataSource;
 /**
- * For information and examples on how to write inputs
- * for custom component actions and triggers, see
- * https://prismatic.io/docs/custom-connectors/actions/#action-inputs.
+ * This function creates an input definition for a custom component action,
+ * trigger, or data source. Inputs define what information is collected from
+ * the user when configuring an integration step.
  *
  * @param definition An InputFieldDefinition object that describes the type of an input for a custom component action or trigger, and information on how it should be displayed in the Prismatic WebApp.
+ * @see {@link https://prismatic.io/docs/custom-connectors/actions/#action-inputs | Action Inputs}
  * @returns This function validates the shape of the `definition` object provided, and returns the same input object.
+ * @example
+ * import { input } from "@prismatic-io/spectral";
+ *
+ * // A basic string input
+ * const itemName = input({
+ *   label: "Item Name",
+ *   type: "string",
+ *   required: true,
+ *   comments: "The name of the item to create",
+ *   example: "My New Item",
+ * });
+ *
+ * @example
+ * import { input } from "@prismatic-io/spectral";
+ *
+ * // A string input with a dropdown of preset choices
+ * const priority = input({
+ *   label: "Priority",
+ *   type: "string",
+ *   required: true,
+ *   model: [
+ *     { label: "Low", value: "low" },
+ *     { label: "Medium", value: "medium" },
+ *     { label: "High", value: "high" },
+ *   ],
+ *   default: "medium",
+ * });
+ *
+ * @example
+ * import { input } from "@prismatic-io/spectral";
+ *
+ * // A code input for JSON
+ * const requestBody = input({
+ *   label: "Request Body",
+ *   type: "code",
+ *   language: "json",
+ *   required: false,
+ *   comments: "JSON body to send with the request",
+ * });
+ *
+ * @example
+ * import { input } from "@prismatic-io/spectral";
+ *
+ * // A key-value list collection input
+ * const headers = input({
+ *   label: "HTTP Headers",
+ *   type: "string",
+ *   collection: "keyvaluelist",
+ *   required: false,
+ *   comments: "Additional headers to include in the request",
+ * });
  */
 const input = (definition) => definition;
 exports.input = input;
 /**
  * This function creates a connection that can be used by a code-native integration
- * or custom component. For information on writing connections, see
- * https://prismatic.io/docs/custom-connectors/connections/.
+ * or custom component. Connections define the fields (API keys, tokens, etc.) needed
+ * to authenticate with a third-party service.
  *
  * @param definition A DefaultConnectionDefinition object that describes the type of a connection for a custom component action or trigger, and information on how it should be displayed in the Prismatic WebApp.
- * @returns This functions validates the shape of the `definition` object provided and returns the same connection object.
+ * @see {@link https://prismatic.io/docs/custom-connectors/connections/ | Writing Custom Connections}
+ * @returns This function validates the shape of the `definition` object provided and returns the same connection object.
+ * @example
+ * import { connection } from "@prismatic-io/spectral";
+ *
+ * const apiKeyConnection = connection({
+ *   key: "apiKey",
+ *   display: {
+ *     label: "Acme API Key",
+ *     description: "Authenticate with Acme using an API key",
+ *   },
+ *   inputs: {
+ *     apiKey: {
+ *       label: "API Key",
+ *       type: "password",
+ *       required: true,
+ *       comments: "Generate an API key from your Acme dashboard",
+ *     },
+ *     baseUrl: {
+ *       label: "Base URL",
+ *       type: "string",
+ *       required: true,
+ *       default: "https://api.acme.com/v2",
+ *     },
+ *   },
+ * });
  */
 const connection = (definition) => definition;
 exports.connection = connection;
 /**
  * This function creates an on-prem connection for a code-native integration or custom component.
- * For information on writing custom component connections using on-prem resources, see
- * https://prismatic.io/docs/integrations/connections/on-prem-agent/#supporting-on-prem-connections-in-a-custom-connector.
+ * On-prem connections include `host` and `port` fields that are automatically overridden by the
+ * on-prem agent with local tunnel endpoints.
  *
  * @param definition An OnPremConnectionDefinition object that describes the type of a connection for a custom component action or trigger, and information on how it should be displayed in the Prismatic WebApp.
+ * @see {@link https://prismatic.io/docs/integrations/connections/on-prem-agent/#supporting-on-prem-connections-in-a-custom-connector | On-Prem Connections}
  * @returns This function validates the shape of the `definition` object provided and returns the same connection object.
+ * @example
+ * import { onPremConnection } from "@prismatic-io/spectral";
+ *
+ * const databaseConnection = onPremConnection({
+ *   key: "onPremDatabase",
+ *   display: {
+ *     label: "On-Prem Database",
+ *     description: "Connect to an on-premise database through the Prismatic agent",
+ *   },
+ *   inputs: {
+ *     host: {
+ *       label: "Host",
+ *       type: "string",
+ *       required: true,
+ *       onPremControlled: true,
+ *       comments: "Overridden when on-prem is enabled",
+ *     },
+ *     port: {
+ *       label: "Port",
+ *       type: "string",
+ *       required: true,
+ *       onPremControlled: true,
+ *       default: "5432",
+ *     },
+ *     username: {
+ *       label: "Username",
+ *       type: "string",
+ *       required: true,
+ *     },
+ *     password: {
+ *       label: "Password",
+ *       type: "password",
+ *       required: true,
+ *     },
+ *   },
+ * });
  */
 const onPremConnection = (definition) => definition;
 exports.onPremConnection = onPremConnection;
 /**
  * This function creates an OAuth 2.0 connection for a code-native integration or custom component.
- * For information on writing an OAuth 2.0 connection, see
- * https://prismatic.io/docs/custom-connectors/connections/#writing-oauth-20-connections.
+ * Supports both Authorization Code and Client Credentials grant types.
  *
  * @param definition An OAuth2ConnectionDefinition object that describes the type of a connection for a custom component action or trigger, and information on how it should be displayed in the Prismatic WebApp.
- * @returns This functions validates the shape of the `definition` object provided and returns the same connection object.
+ * @see {@link https://prismatic.io/docs/custom-connectors/connections/#writing-oauth-20-connections | OAuth 2.0 Connections}
+ * @returns This function validates the shape of the `definition` object provided and returns the same connection object.
+ * @example
+ * import { oauth2Connection, OAuth2Type } from "@prismatic-io/spectral";
+ *
+ * // Authorization Code OAuth 2.0 connection
+ * const acmeOAuth = oauth2Connection({
+ *   key: "acmeOAuth",
+ *   display: {
+ *     label: "Acme OAuth 2.0",
+ *     description: "Authenticate with Acme using OAuth 2.0",
+ *   },
+ *   oauth2Type: OAuth2Type.AuthorizationCode,
+ *   inputs: {
+ *     authorizeUrl: {
+ *       label: "Authorize URL",
+ *       type: "string",
+ *       required: true,
+ *       default: "https://app.acme.com/oauth2/authorize",
+ *       shown: false,
+ *     },
+ *     tokenUrl: {
+ *       label: "Token URL",
+ *       type: "string",
+ *       required: true,
+ *       default: "https://app.acme.com/oauth2/token",
+ *       shown: false,
+ *     },
+ *     scopes: {
+ *       label: "Scopes",
+ *       type: "string",
+ *       required: true,
+ *       default: "read write",
+ *       comments: "Space-delimited OAuth 2.0 permission scopes",
+ *     },
+ *     clientId: {
+ *       label: "Client ID",
+ *       type: "string",
+ *       required: true,
+ *     },
+ *     clientSecret: {
+ *       label: "Client Secret",
+ *       type: "password",
+ *       required: true,
+ *     },
+ *   },
+ * });
  */
 const oauth2Connection = (definition) => definition;
 exports.oauth2Connection = oauth2Connection;
+/**
+ * Register multiple component manifests for a code-native integration.
+ * Each manifest declares a published Prismatic component and the specific
+ * actions, triggers, connections, and data sources your integration uses.
+ *
+ * @param definition A record of Component Manifest objects keyed by component name.
+ * @returns This function returns the same record of component manifests.
+ * @see {@link https://prismatic.io/docs/integrations/code-native/existing-components/ | Using Existing Components}
+ * @example
+ * import { componentManifests } from "@prismatic-io/spectral";
+ *
+ * export const componentRegistry = componentManifests({
+ *   slack: {
+ *     key: "slack",
+ *     public: true,
+ *     actions: {
+ *       postMessage: { inputs: { message: { label: "Message" } } },
+ *     },
+ *   },
+ *   dropbox: {
+ *     key: "dropbox",
+ *     public: true,
+ *     actions: {
+ *       uploadFile: { inputs: { filePath: { label: "File Path" } } },
+ *     },
+ *   },
+ * });
+ */
 const componentManifests = (definition) => definition;
 exports.componentManifests = componentManifests;
-var util_1 = require("./util");
-Object.defineProperty(exports, "util", { enumerable: true, get: function () { return __importDefault(util_1).default; } });
-__exportStar(require("./types"), exports);
+__exportStar(require("./errors"), exports);
 var testing_1 = require("./testing");
 Object.defineProperty(exports, "testing", { enumerable: true, get: function () { return __importDefault(testing_1).default; } });
-__exportStar(require("./errors"), exports);
+__exportStar(require("./types"), exports);
+var util_1 = require("./util");
+Object.defineProperty(exports, "util", { enumerable: true, get: function () { return __importDefault(util_1).default; } });