@prismatic-io/spectral 10.17.2 → 10.18.2

package/dist/integration.d.ts

@@ -2,6 +2,6 @@
  * This module contains functions to help developers create integrations
  * that can run on the Prismatic platform.
  */
-export { integration, flow, configVar, dataSourceConfigVar, connectionConfigVar, customerActivatedConnection, organizationActivatedConnection, componentManifest, componentManifests, onPremConnection, oauth2Connection, } from "./index";
-export * from "./types/typeExportIntegration";
 export * from "./errors";
+export { componentManifest, componentManifests, configVar, connectionConfigVar, customerActivatedConnection, dataSourceConfigVar, flow, integration, oauth2Connection, onPremConnection, organizationActivatedConnection, } from "./index";
+export * from "./types/typeExportIntegration";

package/dist/integration.js

@@ -18,18 +18,18 @@ 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 });
-exports.oauth2Connection = exports.onPremConnection = exports.componentManifests = exports.componentManifest = exports.organizationActivatedConnection = exports.customerActivatedConnection = exports.connectionConfigVar = exports.dataSourceConfigVar = exports.configVar = exports.flow = exports.integration = void 0;
+exports.organizationActivatedConnection = exports.onPremConnection = exports.oauth2Connection = exports.integration = exports.flow = exports.dataSourceConfigVar = exports.customerActivatedConnection = exports.connectionConfigVar = exports.configVar = exports.componentManifests = exports.componentManifest = void 0;
+__exportStar(require("./errors"), exports);
 var index_1 = require("./index");
-Object.defineProperty(exports, "integration", { enumerable: true, get: function () { return index_1.integration; } });
-Object.defineProperty(exports, "flow", { enumerable: true, get: function () { return index_1.flow; } });
+Object.defineProperty(exports, "componentManifest", { enumerable: true, get: function () { return index_1.componentManifest; } });
+Object.defineProperty(exports, "componentManifests", { enumerable: true, get: function () { return index_1.componentManifests; } });
 Object.defineProperty(exports, "configVar", { enumerable: true, get: function () { return index_1.configVar; } });
-Object.defineProperty(exports, "dataSourceConfigVar", { enumerable: true, get: function () { return index_1.dataSourceConfigVar; } });
 Object.defineProperty(exports, "connectionConfigVar", { enumerable: true, get: function () { return index_1.connectionConfigVar; } });
 Object.defineProperty(exports, "customerActivatedConnection", { enumerable: true, get: function () { return index_1.customerActivatedConnection; } });
-Object.defineProperty(exports, "organizationActivatedConnection", { enumerable: true, get: function () { return index_1.organizationActivatedConnection; } });
-Object.defineProperty(exports, "componentManifest", { enumerable: true, get: function () { return index_1.componentManifest; } });
-Object.defineProperty(exports, "componentManifests", { enumerable: true, get: function () { return index_1.componentManifests; } });
-Object.defineProperty(exports, "onPremConnection", { enumerable: true, get: function () { return index_1.onPremConnection; } });
+Object.defineProperty(exports, "dataSourceConfigVar", { enumerable: true, get: function () { return index_1.dataSourceConfigVar; } });
+Object.defineProperty(exports, "flow", { enumerable: true, get: function () { return index_1.flow; } });
+Object.defineProperty(exports, "integration", { enumerable: true, get: function () { return index_1.integration; } });
 Object.defineProperty(exports, "oauth2Connection", { enumerable: true, get: function () { return index_1.oauth2Connection; } });
+Object.defineProperty(exports, "onPremConnection", { enumerable: true, get: function () { return index_1.onPremConnection; } });
+Object.defineProperty(exports, "organizationActivatedConnection", { enumerable: true, get: function () { return index_1.organizationActivatedConnection; } });
 __exportStar(require("./types/typeExportIntegration"), exports);
-__exportStar(require("./errors"), exports);

package/dist/serverTypes/asyncContext.d.ts

@@ -1,4 +1,4 @@
-import { ComponentRegistry, IntegrationDefinition, Inputs, TriggerPayload, TriggerResult } from "../types";
+import { ComponentRegistry, Inputs, IntegrationDefinition, TriggerPayload, TriggerResult } from "../types";
 import type { ActionContext } from "../types/ActionPerformFunction";
 export declare function runWithContext<T>(context: ActionContext, fn: () => T | Promise<T>): T | Promise<T>;
 export declare function requireContext(): ActionContext;

package/dist/serverTypes/context.d.ts

@@ -1,5 +1,5 @@
+import { ActionContext, ComponentManifest, ComponentRegistry, ConfigVarResultCollection, DebugContext, FlowInvoker } from "../types";
 import { ActionContext as ServerActionContext } from ".";
-import { ActionContext, ComponentRegistry, DebugContext, FlowInvoker, ConfigVarResultCollection, ComponentManifest } from "../types";
 export declare function createCNIContext<TConfigVars extends ConfigVarResultCollection = ConfigVarResultCollection, TComponentActions extends Record<string, ComponentManifest["actions"]> = Record<string, ComponentManifest["actions"]>, TFlows extends string[] = string[]>(context: ActionContext<TConfigVars, TComponentActions, TFlows>, componentRegistry: ComponentRegistry): ActionContext<TConfigVars, TComponentActions, TFlows>;
 export declare function createDebugContext(context: ServerActionContext): DebugContext;
 export declare function logDebugResults(context: ActionContext): void;

package/dist/serverTypes/context.js

@@ -16,10 +16,10 @@ exports.createInvokeFlow = void 0;
 exports.createCNIContext = createCNIContext;
 exports.createDebugContext = createDebugContext;
 exports.logDebugResults = logDebugResults;
-const node_process_1 = require("node:process");
 const node_perf_hooks_1 = require("node:perf_hooks");
-const convertIntegration_1 = require("./convertIntegration");
+const node_process_1 = require("node:process");
 const axios_1 = __importDefault(require("axios"));
+const convertIntegration_1 = require("./convertIntegration");
 const MEMORY_USAGE_CONVERSION = 1024 * 1024;
 function createCNIContext(context, componentRegistry) {
     // Component, debug, and invokeFlow methods are not provided as part of the server context.

package/dist/serverTypes/convertComponent.d.ts

@@ -1,6 +1,6 @@
-import { InputFieldDefinition, ComponentDefinition, ConnectionDefinition, Inputs, TriggerDefinition, ComponentHooks, ConfigVarResultCollection, OnPremConnectionInput, TriggerPayload, ConnectionTemplateInputField, ConnectionInput, TriggerResult } from "../types";
-import { Component as ServerComponent, Connection as ServerConnection, Trigger as ServerTrigger, Input as ServerInput } from ".";
+import { ComponentDefinition, ComponentHooks, ConfigVarResultCollection, ConnectionDefinition, ConnectionInput, ConnectionTemplateInputField, InputFieldDefinition, Inputs, OnPremConnectionInput, TriggerDefinition, TriggerPayload, TriggerResult } from "../types";
 import { PollingTriggerDefinition } from "../types/PollingTriggerDefinition";
+import { Component as ServerComponent, Connection as ServerConnection, Input as ServerInput, Trigger as ServerTrigger } from ".";
 export declare const convertInput: (key: string, { default: defaultValue, type, label, collection, ...rest }: InputFieldDefinition | OnPremConnectionInput | ConnectionInput) => ServerInput;
 export declare const _isValidTemplateValue: (template: string, inputs: {
     [key: string]: ConnectionInput | ConnectionTemplateInputField;

package/dist/serverTypes/convertComponent.js

@@ -15,10 +15,10 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.convertComponent = exports.convertConnection = exports.convertTrigger = exports.convertTemplateInput = exports._isValidTemplateValue = exports.convertInput = void 0;
-const types_1 = require("../types");
-const perform_1 = require("./perform");
 const omit_1 = __importDefault(require("lodash/omit"));
+const types_1 = require("../types");
 const PollingTriggerDefinition_1 = require("../types/PollingTriggerDefinition");
+const perform_1 = require("./perform");
 const convertInput = (key, _a) => {
     var { default: defaultValue, type, label, collection } = _a, rest = __rest(_a, ["default", "type", "label", "collection"]);
     const keyLabel = collection === "keyvaluelist" && typeof label === "object" ? label.key : undefined;

package/dist/serverTypes/convertIntegration.d.ts

@@ -1,6 +1,6 @@
-import { IntegrationDefinition, ConfigVar, Flow, ConfigPages, ComponentRegistry, TriggerReference, CollectionType, Inputs, TriggerResult as TriggerPerformResult, ConfigVarResultCollection, QueueConfig, StandardQueueConfig } from "../types";
-import { Component as ServerComponent, ActionContext, TriggerPayload, TriggerResult } from ".";
-import { RequiredConfigVariable as ServerRequiredConfigVariable, ConfigPage as ServerConfigPage, ComponentReference as ServerComponentReference } from "./integration";
+import { CollectionType, ComponentRegistry, ConfigPages, ConfigVar, ConfigVarResultCollection, Flow, Inputs, IntegrationDefinition, QueueConfig, StandardQueueConfig, TriggerResult as TriggerPerformResult, TriggerReference } from "../types";
+import { ActionContext, Component as ServerComponent, TriggerPayload, TriggerResult } from ".";
+import { ComponentReference as ServerComponentReference, ConfigPage as ServerConfigPage, RequiredConfigVariable as ServerRequiredConfigVariable } from "./integration";
 export declare const CONCURRENCY_LIMIT_MAX = 15;
 export declare const CONCURRENCY_LIMIT_MIN = 2;
 export declare const convertIntegration: <TInputs extends Inputs, TActionInputs extends Inputs, TPayload extends TriggerPayload = TriggerPayload, TAllowsBranching extends boolean = boolean, TResult extends TriggerPerformResult<TAllowsBranching, TPayload> = TriggerPerformResult<TAllowsBranching, TPayload>>(definition: IntegrationDefinition<TInputs, TActionInputs, TPayload, TAllowsBranching, TResult>) => ServerComponent<TInputs, TActionInputs, ConfigVarResultCollection, TPayload, TAllowsBranching, TResult>;

package/dist/serverTypes/convertIntegration.js

@@ -13,20 +13,20 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.invokeTriggerComponentInput = exports.convertConfigVar = exports.convertInputValue = exports.convertFlow = exports.convertQueueConfig = exports.convertConfigPages = exports.convertIntegration = exports.CONCURRENCY_LIMIT_MIN = exports.CONCURRENCY_LIMIT_MAX = void 0;
-const yaml_1 = __importDefault(require("yaml"));
-const uuid_1 = require("uuid");
+const fs_1 = require("fs");
 const assign_1 = __importDefault(require("lodash/assign"));
 const camelCase_1 = __importDefault(require("lodash/camelCase"));
+const merge_1 = __importDefault(require("lodash/merge"));
 const pick_1 = __importDefault(require("lodash/pick"));
+const path_1 = __importDefault(require("path"));
+const uuid_1 = require("uuid");
+const yaml_1 = __importDefault(require("yaml"));
 const types_1 = require("../types");
+const asyncContext_1 = require("./asyncContext");
+const context_1 = require("./context");
 const convertComponent_1 = require("./convertComponent");
-const perform_1 = require("./perform");
 const integration_1 = require("./integration");
-const merge_1 = __importDefault(require("lodash/merge"));
-const context_1 = require("./context");
-const asyncContext_1 = require("./asyncContext");
-const path_1 = __importDefault(require("path"));
-const fs_1 = require("fs");
+const perform_1 = require("./perform");
 exports.CONCURRENCY_LIMIT_MAX = 15;
 exports.CONCURRENCY_LIMIT_MIN = 2;
 const convertIntegration = (definition) => {
@@ -55,7 +55,7 @@ const convertIntegration = (definition) => {
         const file = (0, fs_1.readFileSync)(metaDataPath, { encoding: "utf-8" });
         metadata = JSON.parse(file);
     }
-    catch (e) {
+    catch (_e) {
         // No-op. If there's no metadata file then we move on.
     }
     const cniComponent = codeNativeIntegrationComponent(definition, referenceKey, configVars);
@@ -70,7 +70,7 @@ const convertConfigPages = (pages, userLevelConfigured) => {
     }
     return Object.entries(pages).map(([name, { tagline, elements }]) => (Object.assign(Object.assign({ name,
         tagline }, (userLevelConfigured ? { userLevelConfigured } : {})), { elements: Object.entries(elements)
-            .filter(([key, value]) => !(0, types_1.isConnectionScopedConfigVar)(value))
+            .filter(([_key, value]) => !(0, types_1.isConnectionScopedConfigVar)(value))
             .map(([key, value]) => {
             if (typeof value === "string") {
                 return {
@@ -210,7 +210,7 @@ const convertComponentReference = (componentReference, componentRegistry, refere
                 ? manifestEntryInput.default === ""
                     ? []
                     : manifestEntryInput.default
-                : (_c = manifestEntryInput.default) !== null && _c !== void 0 ? _c : "",
+                : ((_c = manifestEntryInput.default) !== null && _c !== void 0 ? _c : ""),
         };
         const type = isCollection ? "complex" : "value" in value ? "value" : "configVar";
         if ("value" in value) {
@@ -505,7 +505,7 @@ const convertConfigVar = (key, configVar, referenceKey, componentRegistry) => {
                     } });
             }, {}),
             orgOnly,
-            meta: Object.assign(Object.assign({}, meta), ("oauth2Config" in configVar ? (_a = configVar.oauth2Config) !== null && _a !== void 0 ? _a : {} : {})),
+            meta: Object.assign(Object.assign({}, meta), ("oauth2Config" in configVar ? ((_a = configVar.oauth2Config) !== null && _a !== void 0 ? _a : {}) : {})),
         };
     }
     if ((0, types_1.isConnectionReferenceConfigVar)(configVar)) {
@@ -520,7 +520,7 @@ const convertConfigVar = (key, configVar, referenceKey, componentRegistry) => {
             connection: Object.assign(Object.assign({}, ref), { template }),
             inputs,
             orgOnly,
-            meta: Object.assign(Object.assign({}, meta), ("oauth2Config" in configVar ? (_b = configVar.oauth2Config) !== null && _b !== void 0 ? _b : {} : {})),
+            meta: Object.assign(Object.assign({}, meta), ("oauth2Config" in configVar ? ((_b = configVar.oauth2Config) !== null && _b !== void 0 ? _b : {}) : {})),
         };
     }
     const rawDefaultValue = "defaultValue" in configVar

package/dist/serverTypes/index.d.ts

@@ -1,15 +1,10 @@
-import { InstanceAttributes, CustomerAttributes, DataSourceType, DataSourceResultType, UserAttributes, TriggerEventFunctionReturn, IntegrationAttributes, FlowAttributes, ConfigVarResultCollection, ComponentManifest, FlowInvoker, ExecutionFrame, DebugContext, FlowSchemas, PollingTriggerPerformFunction, Inputs, TriggerResult as TriggerPerformResult, TriggerPerformFunction } from "../types";
+import { ComponentManifest, ConfigVarResultCollection, CustomerAttributes, DataSourceResultType, DataSourceType, DebugContext, ExecutionFrame, FlowAttributes, FlowInvoker, FlowSchemas, Inputs, InstanceAttributes, IntegrationAttributes, PollingTriggerPerformFunction, TriggerEventFunctionReturn, TriggerPerformFunction, TriggerResult as TriggerPerformResult, UserAttributes } from "../types";
 import type { CNIPollingPerformFunction, ComponentRefTriggerPerformFunction } from "./triggerTypes";
 interface DisplayDefinition {
     label: string;
     description: string;
 }
-export { InstanceAttributes } from "../types";
-export { CustomerAttributes } from "../types";
-export { UserAttributes } from "../types";
-export { IntegrationAttributes } from "../types";
-export { FlowAttributes } from "../types";
-export { FlowSchemas } from "../types";
+export { CustomerAttributes, FlowAttributes, FlowSchemas, InstanceAttributes, IntegrationAttributes, UserAttributes, } from "../types";
 export interface PublishingMetadata {
     flowsWithCustomerRequiredAPIKeys: {
         name: string;

package/dist/serverTypes/perform.d.ts

@@ -1,4 +1,4 @@
-import type { ActionContext, ComponentRegistry, ConfigVarResultCollection, ErrorHandler, Inputs, PollingContext, PollingTriggerDefinition, PollingTriggerPerformFunction, TriggerPayload, TriggerReference, TriggerResult, TriggerPerformFunction } from "../types";
+import type { ActionContext, ComponentRegistry, ConfigVarResultCollection, ErrorHandler, Inputs, PollingContext, PollingTriggerDefinition, PollingTriggerPerformFunction, TriggerPayload, TriggerPerformFunction, TriggerReference, TriggerResult } from "../types";
 import { ComponentReference as ServerComponentReference } from "./integration";
 import type { CNIPollingPerformFunction, ComponentRefTriggerPerformFunction } from "./triggerTypes";
 export type PerformFn = (...args: any[]) => Promise<any>;

package/dist/serverTypes/perform.js

@@ -24,9 +24,9 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createCNIPerform = exports.createCNIComponentRefPerform = exports.createCNIPollingPerform = exports.createPollingPerform = exports.createPerform = exports.cleanParams = exports.createPollingContext = void 0;
-const convertIntegration_1 = require("./convertIntegration");
 const uniq_1 = __importDefault(require("lodash/uniq"));
 const context_1 = require("./context");
+const convertIntegration_1 = require("./convertIntegration");
 const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 const createPollingContext = ({ context, invokeAction, }) => {
     return {

package/dist/testing.d.ts

@@ -4,34 +4,89 @@
  * information on unit testing, check out our docs:
  * https://prismatic.io/docs/custom-connectors/unit-testing/
  */
-import type { ActionPerformReturn as ServerActionPerformReturn, TriggerPayload, TriggerResult, ConnectionValue, ActionLogger, Component, DataSourceResult, DataSourceContext } from "./serverTypes";
-import type { ActionContext, ConnectionDefinition, ActionDefinition, TriggerDefinition, Inputs, ActionInputParameters, DataSourceDefinition, ActionPerformReturn as InvokeActionPerformReturn, TriggerResult as InvokeTriggerResult, DataSourceType, DataSourceResult as InvokeDataSourceResult, TriggerEventFunctionReturn, Flow, ConfigVarResultCollection, ComponentManifest } from "./types";
+import type { ActionLogger, Component, ConnectionValue, DataSourceContext, DataSourceResult, ActionPerformReturn as ServerActionPerformReturn, TriggerPayload, TriggerResult } from "./serverTypes";
+import type { ActionContext, ActionDefinition, ActionInputParameters, ComponentManifest, ConfigVarResultCollection, ConnectionDefinition, DataSourceDefinition, DataSourceType, Flow, Inputs, ActionPerformReturn as InvokeActionPerformReturn, DataSourceResult as InvokeDataSourceResult, TriggerResult as InvokeTriggerResult, TriggerDefinition, TriggerEventFunctionReturn } from "./types";
 /**
- * Create a test connection to use when testing your custom component locally. See
- * https://prismatic.io/docs/custom-connectors/unit-testing/#providing-test-connection-inputs-to-an-action-test
+ * Create a test connection to use when testing your custom component locally.
+ * This builds a `ConnectionValue` from your connection definition and
+ * test credential values.
+ *
+ * @param connectionDef The connection definition (only `key` is used).
+ * @param values A record of field values for the connection (e.g. `apiKey`, `baseUrl`).
+ * @param tokenValues Optional OAuth 2.0 token values (e.g. `access_token`, `refresh_token`).
+ * @param displayName Optional display name for the connection config variable.
+ * @returns A `ConnectionValue` object suitable for use in test invocations.
+ * @see {@link https://prismatic.io/docs/custom-connectors/unit-testing/#providing-test-connection-inputs-to-an-action-test | Test Connection Inputs}
+ * @example
+ * import { testing } from "@prismatic-io/spectral";
+ * import { apiKeyConnection } from "./connections";
+ *
+ * const testConnection = testing.createConnection(apiKeyConnection, {
+ *   apiKey: "test-api-key-123",
+ *   baseUrl: "https://api.acme.com/v2",
+ * });
+ *
+ * // Use with testing.invoke()
+ * const { result } = await testing.invoke(myAction, {
+ *   connection: testConnection,
+ * });
  */
 export declare const createConnection: <T extends ConnectionDefinition>({ key }: T, values: Record<string, unknown>, tokenValues?: Record<string, unknown>, displayName?: string) => ConnectionValue;
 export declare const defaultConnectionValueEnvironmentVariable = "PRISMATIC_CONNECTION_VALUE";
 /**
- * Source a test connection from an environment variable for local testing. See
- * https://prismatic.io/docs/custom-connectors/unit-testing/#access-connections-for-local-testing
+ * Source a test connection from an environment variable for local testing.
+ * The environment variable should contain a JSON-serialized connection value.
+ * Defaults to reading from `PRISMATIC_CONNECTION_VALUE`.
+ *
+ * @param envVarKey The name of the environment variable to read. Defaults to `"PRISMATIC_CONNECTION_VALUE"`.
+ * @returns A `ConnectionValue` parsed from the environment variable.
+ * @see {@link https://prismatic.io/docs/custom-connectors/unit-testing/#access-connections-for-local-testing | Access Connections for Local Testing}
+ * @example
+ * import { testing } from "@prismatic-io/spectral";
+ *
+ * // Reads from PRISMATIC_CONNECTION_VALUE env var (default)
+ * const conn = testing.connectionValue();
+ *
+ * // Or specify a custom env var
+ * const conn = testing.connectionValue("MY_ACME_CONNECTION");
  */
 export declare const connectionValue: (envVarKey?: string) => ConnectionValue;
 /**
- * Pre-built mock of ActionLogger. Suitable for asserting logs are created as expected. See
- * https://prismatic.io/docs/custom-connectors/unit-testing/#verifying-correct-logging-in-action-tests
- * for information on testing correct logging behavior in your custom component.
+ * Pre-built mock of ActionLogger. All log methods (`info`, `warn`, `error`, etc.)
+ * are Jest spies, so you can assert that your actions log the expected messages.
+ *
+ * @returns A mock `ActionLogger` with Jest spy methods.
+ * @see {@link https://prismatic.io/docs/custom-connectors/unit-testing/#verifying-correct-logging-in-action-tests | Verifying Logging}
+ * @example
+ * import { testing } from "@prismatic-io/spectral";
+ *
+ * const logger = testing.loggerMock();
+ * // Pass logger in context, then assert:
+ * expect(logger.info).toHaveBeenCalledWith("Processing started");
  */
 export declare const loggerMock: () => ActionLogger;
 /**
- * Creates basic component mocks based on the CNI's component registry.
- * You may pass mock overrides in the second argument, e.g.:
+ * Creates basic component action mocks based on a code-native integration's
+ * component registry. Each action mock returns the action's `examplePayload`
+ * by default. Pass overrides in the second argument to customize specific mocks.
+ *
+ * @param registry The component registry (or subset) to mock.
+ * @param mocks Optional overrides for specific component actions.
+ * @returns An object of mocked component actions, suitable for use in test context.
+ * @see {@link https://prismatic.io/docs/custom-connectors/unit-testing/ | Unit Testing}
+ * @example
+ * import { createMockContextComponents } from "@prismatic-io/spectral/dist/testing";
+ * import { componentRegistry } from "./componentRegistry";
+ *
+ * // Default mocks (uses examplePayload from the manifest)
+ * const components = createMockContextComponents(componentRegistry);
  *
- * createMockContextComponents(myManifest, {
+ * // With custom overrides
+ * const components = createMockContextComponents(componentRegistry, {
  *   actions: {
- *     myComponentName: {
- *        myComponentAction: () => Promise.resolve({ data: "my test data "}),
- *     }
+ *     slack: {
+ *       postMessage: () => Promise.resolve({ data: { ok: true } }),
+ *     },
  *   },
  * });
  */
@@ -48,24 +103,82 @@ interface InvokeReturn<ReturnData> {
     loggerMock: ActionLogger;
 }
 /**
- * Invokes specified ActionDefinition perform function using supplied params
- * and optional context. Accepts a generic type matching ActionPerformReturn 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.
+ * Invokes a custom component action's `perform` function within a test harness.
+ * Returns both the action result and a mock logger for asserting logging behavior.
+ *
+ * @param actionDef The action definition to test (only `perform` is used).
+ * @param params Input parameter values to pass to the action's `perform` function.
+ * @param context Optional partial context overrides (e.g. custom `configVars` or `instanceState`).
+ * @returns An object with `result` (the action's return value) and `loggerMock` (for asserting logs).
+ * @see {@link https://prismatic.io/docs/custom-connectors/unit-testing/ | Unit Testing}
+ * @example
+ * import { testing } from "@prismatic-io/spectral";
+ * import { myAction } from "./actions";
+ *
+ * it("should return items", async () => {
+ *   const { result, loggerMock } = await testing.invoke(myAction, {
+ *     connection: testConnection,
+ *     limit: "10",
+ *   });
+ *
+ *   expect(result.data).toHaveProperty("items");
+ *   expect(loggerMock.info).toHaveBeenCalled();
+ * });
  */
 export declare const invoke: <TInputs extends Inputs, TConfigVars extends ConfigVarResultCollection, TAllowsBranching extends boolean, TReturn extends InvokeActionPerformReturn<TAllowsBranching, unknown>>({ perform }: ActionDefinition<TInputs, TConfigVars, TAllowsBranching, TReturn>, params: ActionInputParameters<TInputs>, context?: Partial<ActionContext<TConfigVars>>) => Promise<InvokeReturn<TReturn>>;
 export declare const defaultTriggerPayload: () => TriggerPayload;
 /**
- * Invokes specified TriggerDefinition perform function using supplied params
- * and optional context. Accepts a generic type matching TriggerResult as a convenience
- * to avoid extra casting within test methods. Returns an InvokeResult containing both the
- * trigger result and a mock logger for asserting logging.
+ * Invokes a custom component trigger's `perform` function within a test harness.
+ * Provides a default trigger payload that can be overridden. Returns both the
+ * trigger result and a mock logger for asserting logging behavior.
+ *
+ * @param triggerDef The trigger definition to test (only `perform` is used).
+ * @param context Optional partial context overrides.
+ * @param payload Optional partial trigger payload overrides (merged with defaults).
+ * @param params Optional input parameter values for the trigger.
+ * @returns An object with `result` (the trigger's return value) and `loggerMock`.
+ * @see {@link https://prismatic.io/docs/custom-connectors/unit-testing/ | Unit Testing}
+ * @example
+ * import { testing } from "@prismatic-io/spectral";
+ * import { webhookTrigger } from "./triggers";
+ *
+ * it("should process the webhook payload", async () => {
+ *   const { result } = await testing.invokeTrigger(
+ *     webhookTrigger,
+ *     undefined, // use default context
+ *     {
+ *       body: { data: JSON.stringify({ event: "created" }) },
+ *       headers: { "x-webhook-secret": "test-secret" },
+ *     },
+ *     { secret: "test-secret" },
+ *   );
+ *
+ *   expect(result.payload).toBeDefined();
+ * });
  */
 export declare const invokeTrigger: <TInputs extends Inputs, TConfigVars extends ConfigVarResultCollection, TAllowsBranching extends boolean, TResult extends InvokeTriggerResult<TAllowsBranching, TriggerPayload>>({ perform }: TriggerDefinition<TInputs, TConfigVars, TAllowsBranching, TResult>, context?: Partial<ActionContext<TConfigVars>>, payload?: TriggerPayload, params?: ActionInputParameters<TInputs>) => Promise<InvokeReturn<TResult>>;
 /**
- * Invokes specified DataSourceDefinition perform function using supplied params.
- * Accepts a generic type matching DataSourceResult as a convenience to avoid extra
- * casting within test methods. Returns a DataSourceResult.
+ * Invokes a custom component data source's `perform` function within a test harness.
+ * Returns the data source result directly.
+ *
+ * @param dataSourceDef The data source definition to test (only `perform` is used).
+ * @param params Input parameter values to pass to the data source's `perform` function.
+ * @param context Optional partial context overrides.
+ * @returns The data source result (e.g. a picklist, JSON form, or other data source type).
+ * @see {@link https://prismatic.io/docs/custom-connectors/unit-testing/ | Unit Testing}
+ * @example
+ * import { testing } from "@prismatic-io/spectral";
+ * import { selectChannel } from "./dataSources";
+ *
+ * it("should return a list of channels", async () => {
+ *   const result = await testing.invokeDataSource(selectChannel, {
+ *     connection: testConnection,
+ *   });
+ *
+ *   expect(result.result).toContainEqual(
+ *     expect.objectContaining({ label: "General" }),
+ *   );
+ * });
  */
 export declare const invokeDataSource: <TInputs extends Inputs, TConfigVars extends ConfigVarResultCollection, TDataSourceType extends DataSourceType>({ perform }: DataSourceDefinition<TInputs, TConfigVars, TDataSourceType>, params: ActionInputParameters<TInputs>, context?: Partial<DataSourceContext<TConfigVars>>) => Promise<InvokeDataSourceResult<TDataSourceType>>;
 type TestConnectionValue = Pick<ConnectionValue, "fields" | "context" | "token" | "key">;
@@ -74,9 +187,35 @@ type ToTestValues<TConfigVars extends ConfigVarResultCollection> = {
     [K in keyof TConfigVars]: TConfigVars[K] extends ConnectionDefinition ? TestConnectionValue : string;
 };
 /**
- * Invokes specified Flow of a Code Native Integration using supplied params.
- * Runs the Trigger and then the Action function and returns the result of the Action. See
- * https://prismatic.io/docs/integrations/triggers/cross-flow/#using-cross-flow-triggers-in-code-native
+ * Invokes a code-native integration flow within a test harness. Runs the
+ * flow's `onTrigger` (if defined) followed by `onExecution`, and returns
+ * the execution result. Accepts optional config variables, context overrides,
+ * and a custom trigger payload.
+ *
+ * @param flow The flow definition to test.
+ * @param options Optional config variables, context overrides, and trigger payload.
+ * @returns An object with `result` (the flow execution return value) and `loggerMock`.
+ * @see {@link https://prismatic.io/docs/custom-connectors/unit-testing/ | Unit Testing}
+ * @example
+ * import { invokeFlow } from "@prismatic-io/spectral/dist/testing";
+ * import { myFlow } from "./flows";
+ *
+ * it("should execute the flow end-to-end", async () => {
+ *   const { result } = await invokeFlow(myFlow, {
+ *     configVars: {
+ *       "Acme API Endpoint": "https://api.acme.com",
+ *       "Acme Connection": {
+ *         fields: { apiKey: "test-key" },
+ *         key: "apiKey",
+ *       },
+ *     },
+ *     payload: {
+ *       body: { data: JSON.stringify({ event: "created" }) },
+ *     },
+ *   });
+ *
+ *   expect(result.data).toBeDefined();
+ * });
  */
 export declare const invokeFlow: <TInputs extends Inputs, TActionInputs extends Inputs, TConfigVars extends ConfigVarResultCollection = ConfigVarResultCollection, TConfigVarValues extends TestConfigVarValues = ToTestValues<TConfigVars>, TPayload extends TriggerPayload = TriggerPayload, TAllowsBranching extends boolean = boolean, TResult extends InvokeTriggerResult<TAllowsBranching, TPayload> = InvokeTriggerResult<TAllowsBranching, TPayload>>(flow: Flow<TInputs, TActionInputs, TPayload, TAllowsBranching, TResult>, { configVars, context, payload, }?: {
     configVars?: TConfigVarValues;
@@ -119,8 +258,33 @@ export declare class ComponentTestHarness<TInputs extends Inputs, TActionInputs
     dataSource<TConfigVars extends ConfigVarResultCollection>(key: string, params?: Record<string, unknown>, context?: Partial<DataSourceContext<TConfigVars>>): Promise<DataSourceResult>;
 }
 /**
- * Create a testing harness to test a custom component's actions, triggers and data sources. See
- * https://prismatic.io/docs/custom-connectors/unit-testing/
+ * Create a testing harness to test a custom component's actions, triggers
+ * and data sources by key. The harness automatically provides default input
+ * values and mock context.
+ *
+ * @param component The compiled component object (the result of calling `component()`).
+ * @returns A `ComponentTestHarness` instance with `.action()`, `.trigger()`, and `.dataSource()` methods.
+ * @see {@link https://prismatic.io/docs/custom-connectors/unit-testing/ | Unit Testing}
+ * @example
+ * import { testing } from "@prismatic-io/spectral";
+ * import myComponent from ".";
+ *
+ * const harness = testing.createHarness(myComponent);
+ *
+ * it("should list items", async () => {
+ *   const result = await harness.action("listItems", {
+ *     connection: testConnection,
+ *     limit: "10",
+ *   });
+ *   expect(result.data).toHaveProperty("items");
+ * });
+ *
+ * it("should handle a webhook trigger", async () => {
+ *   const result = await harness.trigger("webhook", {
+ *     body: { data: '{"event":"created"}' },
+ *   });
+ *   expect(result.payload).toBeDefined();
+ * });
  */
 export declare const createHarness: <TInputs extends Inputs, TActionInputs extends Inputs, TConfigVars extends ConfigVarResultCollection = ConfigVarResultCollection, TPayload extends TriggerPayload = TriggerPayload, TAllowsBranching extends boolean = boolean, TResult extends InvokeTriggerResult<TAllowsBranching, TPayload> = InvokeTriggerResult<TAllowsBranching, TPayload>, TComponent extends Component<TInputs, TActionInputs, TConfigVars, TPayload, TAllowsBranching, TResult> = Component<TInputs, TActionInputs, TConfigVars, TPayload, TAllowsBranching, TResult>>(component: TComponent) => ComponentTestHarness<TInputs, TActionInputs, TConfigVars, TPayload, TAllowsBranching, TResult, TComponent>;
 declare const _default: {