@prismatic-io/spectral 10.18.7-preview.3 → 10.18.7-preview.5

package/dist/serverTypes/convertComponent.d.ts

@@ -7,6 +7,12 @@ import { type CleanFn } from "./perform";
  * declare a top-level clean on these containers — the conversion always
  * supplies one so nested clean functions are applied at runtime. */
 export declare const cleanerFor: (input: InputFieldDefinition) => CleanFn | undefined;
+/**
+ * Throws if `batchSize` isn't a positive integer; otherwise returns it.
+ * Shared by both component-trigger (`TriggerResolver.default.batchSize`) and
+ * CNI flow (`TriggerResolverConfig.batchSize`) validation paths.
+ */
+export declare const validateBatchSize: (ownerLabel: string, fieldName: string, batchSize: unknown) => number;
 export declare const convertInput: (key: string, definition: InputFieldDefinition | OnPremConnectionInput | ConnectionInput) => ServerInput;
 export declare const _isValidTemplateValue: (template: string, inputs: {
     [key: string]: ConnectionInput | ConnectionTemplateInputField;

package/dist/serverTypes/convertComponent.js

@@ -14,7 +14,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.convertComponent = exports.convertConnection = exports.convertTrigger = exports.convertTemplateInput = exports._isValidTemplateValue = exports.convertInput = exports.cleanerFor = void 0;
+exports.convertComponent = exports.convertConnection = exports.convertTrigger = exports.convertTemplateInput = exports._isValidTemplateValue = exports.convertInput = exports.validateBatchSize = exports.cleanerFor = void 0;
 const omit_1 = __importDefault(require("lodash/omit"));
 const types_1 = require("../types");
 const PollingTriggerDefinition_1 = require("../types/PollingTriggerDefinition");
@@ -60,6 +60,34 @@ const cleanerFor = (input) => {
     return "clean" in input ? input.clean : undefined;
 };
 exports.cleanerFor = cleanerFor;
+/**
+ * Throws if `batchSize` isn't a positive integer; otherwise returns it.
+ * Shared by both component-trigger (`TriggerResolver.default.batchSize`) and
+ * CNI flow (`TriggerResolverConfig.batchSize`) validation paths.
+ */
+const validateBatchSize = (ownerLabel, fieldName, batchSize) => {
+    if (typeof batchSize !== "number" || !Number.isInteger(batchSize) || batchSize < 1) {
+        throw new Error(`${ownerLabel} has an invalid ${fieldName} batchSize of ${String(batchSize)}. batchSize must be an integer >= 1.`);
+    }
+    return batchSize;
+};
+exports.validateBatchSize = validateBatchSize;
+const buildTriggerResolverFields = (triggerLabel, support, resolver) => {
+    if (!resolver) {
+        return support === "invalid" ? {} : { triggerResolverDefaultBatchSize: 1 };
+    }
+    return Object.assign(Object.assign({ triggerResolverDefaultBatchSize: (0, exports.validateBatchSize)(`Trigger "${triggerLabel}"`, "triggerResolver.default", resolver.default.batchSize) }, (resolver.resolveItems
+        ? {
+            resolveTriggerItems: resolver.resolveItems,
+            hasResolveTriggerItems: true,
+        }
+        : {})), (resolver.getNextDiscoveryState
+        ? {
+            getNextDiscoveryState: resolver.getNextDiscoveryState,
+            hasGetNextDiscoveryState: true,
+        }
+        : {}));
+};
 const convertInput = (key, definition) => {
     // Cast: the field union is wider than any single member; runtime guards below handle it.
     const _a = definition, { default: defaultValue, type, label, collection, inputs: childInputs, configurations } = _a, rest = __rest(_a, ["default", "type", "label", "collection", "inputs", "configurations"]);
@@ -143,6 +171,18 @@ const convertTrigger = (triggerKey, trigger, hooks) => {
     });
     const triggerInputCleaners = Object.entries(inputs).reduce((result, [key, value]) => (Object.assign(Object.assign({}, result), { [key]: (0, exports.cleanerFor)(value) })), {});
     let scheduleSupport = "scheduleSupport" in trigger ? trigger.scheduleSupport : "invalid";
+    const triggerResolver = "triggerResolver" in trigger ? trigger.triggerResolver : undefined;
+    const triggerResolverSupport = "triggerResolverSupport" in trigger && trigger.triggerResolverSupport !== undefined
+        ? trigger.triggerResolverSupport
+        : triggerResolver
+            ? "valid"
+            : "invalid";
+    if (triggerResolverSupport === "required" && !triggerResolver) {
+        throw new Error(`Trigger "${trigger.display.label}" declares triggerResolverSupport "required" but is missing triggerResolver.`);
+    }
+    if (triggerResolverSupport === "invalid" && triggerResolver) {
+        throw new Error(`Trigger "${trigger.display.label}" declares triggerResolver but triggerResolverSupport is "invalid".`);
+    }
     let convertedActionInputs = [];
     let performToUse;
     if ((0, PollingTriggerDefinition_1.isPollingTriggerDefinition)(trigger)) {
@@ -171,11 +211,11 @@ const convertTrigger = (triggerKey, trigger, hooks) => {
             errorHandler: hooks === null || hooks === void 0 ? void 0 : hooks.error,
         });
     }
-    const result = Object.assign(Object.assign(Object.assign({}, trigger), { key: triggerKey, inputs: convertedTriggerInputs.concat(convertedActionInputs), perform: performToUse, scheduleSupport, synchronousResponseSupport: "synchronousResponseSupport" in trigger
+    const result = Object.assign(Object.assign(Object.assign(Object.assign({}, trigger), { key: triggerKey, inputs: convertedTriggerInputs.concat(convertedActionInputs), perform: performToUse, scheduleSupport, synchronousResponseSupport: "synchronousResponseSupport" in trigger
             ? trigger.synchronousResponseSupport
             : scheduleSupport === "invalid"
                 ? "valid"
-                : "invalid" }), ((0, PollingTriggerDefinition_1.isPollingTriggerDefinition)(trigger) ? { isPollingTrigger: true } : {}));
+                : "invalid", triggerResolverSupport }), buildTriggerResolverFields(trigger.display.label, triggerResolverSupport, triggerResolver)), ((0, PollingTriggerDefinition_1.isPollingTriggerDefinition)(trigger) ? { isPollingTrigger: true } : {}));
     if (onInstanceDeploy) {
         result.onInstanceDeploy = (0, perform_1.createPerform)(onInstanceDeploy, {
             inputCleaners: triggerInputCleaners,

package/dist/serverTypes/convertIntegration.js

@@ -29,6 +29,12 @@ const integration_1 = require("./integration");
 const perform_1 = require("./perform");
 exports.CONCURRENCY_LIMIT_MAX = 15;
 exports.CONCURRENCY_LIMIT_MIN = 2;
+const validateFlowResolverBatchSize = (flowName, configName, resolver) => {
+    if (!resolver) {
+        return undefined;
+    }
+    return { batchSize: (0, convertComponent_1.validateBatchSize)(flowName, configName, resolver.batchSize) };
+};
 const convertIntegration = (definition) => {
     var _a, _b, _c;
     // Generate a unique reference key that will be used to reference the
@@ -403,6 +409,10 @@ const convertFlow = (flow, componentRegistry, referenceKey) => {
             }
             : {}));
     }
+    const triggerResolver = "triggerResolver" in flow ? flow.triggerResolver : undefined;
+    if (triggerResolver) {
+        result.triggerResolver = validateFlowResolverBatchSize(flow.name, "triggerResolver", triggerResolver);
+    }
     const actionStep = {
         action: {
             key: flowFunctionKey(flow.name, "onExecution"),
@@ -670,7 +680,11 @@ function generateTriggerPerformFn(params) {
         case "standard":
             return (0, perform_1.createCNIPerform)({ componentRegistry, onTrigger });
         case "component-ref":
-            return (0, perform_1.createCNIComponentRefPerform)({ componentRegistry, componentRef, onTrigger });
+            return (0, perform_1.createCNIComponentRefPerform)({
+                componentRegistry,
+                componentRef,
+                onTrigger,
+            });
         default:
             throw new Error(`Invalid trigger configuration detected: ${JSON.stringify(params, null, 2)}`);
     }
@@ -739,7 +753,7 @@ const codeNativeIntegrationComponent = ({ name, iconPath, description, flows = [
                 inputs: [],
             } });
     }, {});
-    const convertedTriggers = flows.reduce((result, { name, onTrigger, onInstanceDeploy, onInstanceDelete, webhookLifecycleHandlers, schedule, triggerType, }) => {
+    const convertedTriggers = flows.reduce((result, { name, onTrigger, onInstanceDeploy, onInstanceDelete, webhookLifecycleHandlers, schedule, triggerType, triggerResolver, }) => {
         if (!flowUsesWrapperTrigger({
             onTrigger,
             onInstanceDelete,
@@ -774,26 +788,21 @@ const codeNativeIntegrationComponent = ({ name, iconPath, description, flows = [
         const deployFn = generateTriggerEventWrapperFn(ref, onTrigger, "onInstanceDeploy", componentRegistry, onInstanceDeploy);
         const webhookCreateFn = generateTriggerEventWrapperFn(ref, onTrigger, "webhookCreate", componentRegistry, webhookLifecycleHandlers === null || webhookLifecycleHandlers === void 0 ? void 0 : webhookLifecycleHandlers.create);
         const webhookDeleteFn = generateTriggerEventWrapperFn(ref, onTrigger, "webhookDelete", componentRegistry, webhookLifecycleHandlers === null || webhookLifecycleHandlers === void 0 ? void 0 : webhookLifecycleHandlers.delete);
-        return Object.assign(Object.assign({}, result), { [key]: {
-                key,
-                display: {
+        return Object.assign(Object.assign({}, result), { [key]: Object.assign({ key, display: {
                     label: `${name} - onTrigger`,
                     description: "The function that will be executed by the flow to return an HTTP response.",
-                },
-                perform: performFn,
-                onInstanceDeploy: deployFn,
-                hasOnInstanceDeploy: !!deployFn,
-                onInstanceDelete: deleteFn,
-                hasOnInstanceDelete: !!deleteFn,
-                webhookCreate: webhookCreateFn,
-                hasWebhookCreateFunction: !!webhookCreateFn,
-                webhookDelete: webhookDeleteFn,
-                hasWebhookDeleteFunction: !!webhookDeleteFn,
-                inputs: [],
-                scheduleSupport: triggerType === "polling" ? "required" : "valid",
-                synchronousResponseSupport: "valid",
-                isPollingTrigger: triggerType === "polling",
-            } });
+                }, perform: performFn, onInstanceDeploy: deployFn, hasOnInstanceDeploy: !!deployFn, onInstanceDelete: deleteFn, hasOnInstanceDelete: !!deleteFn, webhookCreate: webhookCreateFn, hasWebhookCreateFunction: !!webhookCreateFn, webhookDelete: webhookDeleteFn, hasWebhookDeleteFunction: !!webhookDeleteFn, inputs: [], scheduleSupport: triggerType === "polling" ? "required" : "valid", synchronousResponseSupport: "valid", isPollingTrigger: triggerType === "polling", triggerResolverSupport: triggerResolver ? "valid" : "invalid" }, (triggerResolver
+                ? Object.assign(Object.assign({ triggerResolverDefaultBatchSize: triggerResolver.batchSize }, (triggerResolver.resolveItems
+                    ? {
+                        resolveTriggerItems: triggerResolver.resolveItems,
+                        hasResolveTriggerItems: true,
+                    }
+                    : {})), (triggerResolver.getNextDiscoveryState
+                    ? {
+                        getNextDiscoveryState: triggerResolver.getNextDiscoveryState,
+                        hasGetNextDiscoveryState: true,
+                    }
+                    : {})) : {})) });
     }, {});
     const convertedDataSources = Object.entries(configVars).reduce((result, [key, configVar]) => {
         if (!(0, types_1.isDataSourceDefinitionConfigVar)(configVar)) {

package/dist/serverTypes/index.d.ts

@@ -112,8 +112,8 @@ interface HttpResponse {
     headers?: Record<string, string>;
     body?: string;
 }
-interface TriggerBaseResult {
-    payload: TriggerPayload;
+interface TriggerBaseResult<TPayload extends TriggerPayload = TriggerPayload> {
+    payload: TPayload;
     response?: HttpResponse;
     instanceState?: Record<string, unknown>;
     crossFlowState?: Record<string, unknown>;
@@ -122,12 +122,18 @@ interface TriggerBaseResult {
     failed?: boolean;
     error?: Record<string, unknown>;
 }
-interface TriggerBranchingResult extends TriggerBaseResult {
+interface TriggerBranchingResult<TPayload extends TriggerPayload = TriggerPayload> extends TriggerBaseResult<TPayload> {
     branch: string;
 }
-export type TriggerResult = TriggerBranchingResult | TriggerBaseResult | undefined;
+export type TriggerResult<TPayload extends TriggerPayload = TriggerPayload> = TriggerBranchingResult<TPayload> | TriggerBaseResult<TPayload> | undefined;
 export type TriggerEventFunctionResult = TriggerEventFunctionReturn | void;
 export type TriggerEventFunction = (context: ActionContext, params: Record<string, unknown>) => Promise<TriggerEventFunctionResult>;
+/**
+ * Wire format the platform expects for a trigger. Note: function references
+ * (perform, resolveTriggerItems, getNextDiscoveryState, ...) don't survive JSON
+ * serialization, so each callback has a paired `hasXxx: boolean` flag the
+ * server reads to detect presence. Keep the flag and its callback in sync.
+ */
 export interface Trigger<TInputs extends Inputs, TActionInputs extends Inputs, TConfigVars extends ConfigVarResultCollection = ConfigVarResultCollection, TPayload extends TriggerPayload = TriggerPayload, TAllowsBranching extends boolean = boolean, TResult extends TriggerPerformResult<TAllowsBranching, TPayload> = TriggerPerformResult<TAllowsBranching, TPayload>> {
     key: string;
     display: DisplayDefinition & {
@@ -155,6 +161,12 @@ export interface Trigger<TInputs extends Inputs, TActionInputs extends Inputs, T
     hasWebhookDeleteFunction?: boolean;
     scheduleSupport: TriggerOptionChoice;
     synchronousResponseSupport: TriggerOptionChoice;
+    triggerResolverSupport?: TriggerOptionChoice;
+    triggerResolverDefaultBatchSize?: number;
+    resolveTriggerItems?: (context: ActionContext<TConfigVars>, result: TriggerBaseResult<TPayload>) => unknown[];
+    hasResolveTriggerItems?: boolean;
+    getNextDiscoveryState?: (context: ActionContext<TConfigVars>, result: TriggerBaseResult<TPayload>) => Record<string, unknown> | null;
+    hasGetNextDiscoveryState?: boolean;
     examplePayload?: unknown;
     isCommonTrigger?: boolean;
     isPollingTrigger?: boolean;

package/dist/types/Inputs.d.ts

@@ -291,15 +291,19 @@ export type DateTimeInputField = BaseInputField & {
     /** Clean function. */
     clean?: InputCleanFunction<unknown>;
 } & CollectionOptions<string>;
-/** `InputFieldDefinition` minus container input types; used to cap
- * structuredObject nesting at one level and to enforce leaf-only positions. */
-export type LeafInputFieldDefinition = Exclude<InputFieldDefinition, StructuredObjectInputField | DynamicObjectInputField>;
-/** `InputFieldDefinition` minus `DynamicObjectInputField`; used inside a
- * dynamicObject's `configurations.<key>.inputs` to allow leaves *and*
- * structuredObject children while still rejecting nested dynamicObjects. */
-export type StructuredOrLeafInputFieldDefinition = Exclude<InputFieldDefinition, DynamicObjectInputField>;
+/** `InputFieldDefinition` minus container input types and connection
+ * pickers. Connections resolve to config-var references outside the
+ * parent's value tree, so they're only valid at the top level — never as
+ * a child of a structuredObject or a dynamicObject configuration. */
+export type LeafInputFieldDefinition = Exclude<InputFieldDefinition, StructuredObjectInputField | DynamicObjectInputField | ConnectionInputField | ConnectionTemplateInputField>;
+/** `LeafInputFieldDefinition` plus `StructuredObjectInputField`; used
+ * inside a dynamicObject's `configurations.<key>.inputs` to allow leaves
+ * and structuredObject children while still rejecting nested
+ * dynamicObjects and connection pickers. */
+export type StructuredOrLeafInputFieldDefinition = LeafInputFieldDefinition | StructuredObjectInputField;
 /** Groups related primitive inputs under a single named container.
- * Nesting is capped at one level. */
+ * Nesting is capped at one level. Connection pickers are rejected as
+ * children — they may only appear at the top level. */
 export type StructuredObjectInputField = Omit<BaseInputField, "dataSource"> & {
     /** Data type the input will collect. */
     type: "structuredObject";
@@ -317,9 +321,7 @@ export interface DynamicObjectConfiguration {
     } | string;
     /** Additional text to give guidance to the user when this configuration is selected. */
     comments?: string;
-    /** Inputs that become available when this configuration is selected. May
-     * include leaf inputs and structuredObject inputs; nested dynamicObjects
-     * are rejected at the type level. */
+    /** Inputs that become available when this configuration is selected. */
     inputs: Record<string, StructuredOrLeafInputFieldDefinition>;
 }
 /** Presents a discriminated set of input groups; the user picks a configuration

package/dist/types/IntegrationDefinition.d.ts

@@ -4,13 +4,13 @@ import type { ComponentRegistry, ConfigVarExpression, TriggerReference, ValueExp
 import type { ConfigPages, UserLevelConfigPages } from "./ConfigPages";
 import type { ConfigVars } from "./ConfigVars";
 import type { FlowDefinitionFlowSchema } from "./FlowSchemas";
-import type { Inputs } from "./Inputs";
+import type { ConfigVarResultCollection, Inputs } from "./Inputs";
 import type { PollingTriggerPerformFunction } from "./PollingTriggerDefinition";
 import type { ScopedConfigVarMap } from "./ScopedConfigVars";
 import type { TriggerEventFunction } from "./TriggerEventFunction";
 import type { TriggerPayload } from "./TriggerPayload";
 import type { TriggerPerformFunction } from "./TriggerPerformFunction";
-import type { TriggerResult } from "./TriggerResult";
+import type { TriggerBaseResult, TriggerResult } from "./TriggerResult";
 /**
  * Defines attributes of a code-native integration. See
  * https://prismatic.io/docs/integrations/code-native/
@@ -117,6 +117,13 @@ interface FlowBase<TTriggerPayload extends TriggerPayload = TriggerPayload> {
      */
     organizationApiKeys?: string[];
     testApiKeys?: string[];
+    /**
+     * Trigger resolver configuration: batches the records returned by the
+     * trigger into parallel dispatches. When using an existing component
+     * trigger, that trigger must declare `triggerResolverSupport`. CNI flows
+     * infer support from the resolver's presence.
+     */
+    triggerResolver?: TriggerResolverConfig<ConfigVars, TTriggerPayload>;
     /** Error handling configuration. */
     errorConfig?: StepErrorConfig;
     /** Optional schemas definitions for the flow. Currently only for use with AI agents. */
@@ -246,4 +253,15 @@ export type EndpointType = "flow_specific" | "instance_specific" | "shared_insta
 export type EndpointSecurityType = "unsecured" | "customer_optional" | "customer_required" | "organization";
 /** Choices of Step Error Handlers that define the behavior when a step error occurs. */
 export type StepErrorHandlerType = "fail" | "ignore" | "retry";
+/** Configures how trigger items are batched when the trigger supports a resolver. */
+export type TriggerResolverConfig<TConfigVars extends ConfigVarResultCollection = ConfigVarResultCollection, TPayload extends TriggerPayload = TriggerPayload, TItem = unknown> = {
+    /** Number of items per batch. Must be an integer >= 1. `1` dispatches each item individually; `>1` groups items into batches. */
+    batchSize: number;
+    /** Extracts an array of items from the trigger result for batched dispatch. Receives the same context as the trigger's perform function. */
+    resolveItems?: (context: ActionContext<TConfigVars>, result: TriggerBaseResult<TPayload>) => TItem[];
+    /** Called after each trigger run. When defined and returns a non-null object, the platform
+     *  queues another pagination round (re-invokes the trigger) and stamps the returned object
+     *  onto `payload.discoveryState` for that next invocation. Return `null` to stop. */
+    getNextDiscoveryState?: (context: ActionContext<TConfigVars>, result: TriggerBaseResult<TPayload>) => Record<string, unknown> | null;
+};
 export {};

package/dist/types/PollingTriggerDefinition.d.ts

@@ -4,6 +4,7 @@ import type { ActionContext } from "./ActionPerformFunction";
 import type { ActionPerformReturn } from "./ActionPerformReturn";
 import type { ActionDisplayDefinition } from "./DisplayDefinition";
 import type { ConfigVarResultCollection, Inputs } from "./Inputs";
+import type { TriggerResolverDecl } from "./TriggerDefinition";
 import type { TriggerEventFunction } from "./TriggerEventFunction";
 import type { TriggerPayload } from "./TriggerPayload";
 import type { TriggerResult } from "./TriggerResult";
@@ -18,8 +19,12 @@ export type PollingTriggerPerformFunction<TInputs extends Inputs, TActionInputs
 /**
  * PollingTriggerDefinition is the type of the object that is passed in to `pollingTrigger` function to
  * define a component trigger.
+ *
+ * Composed from `PollingTriggerDefinitionBase` plus `TriggerResolverDecl`, which
+ * enforces the resolver support relationship at the type level.
  */
-export interface PollingTriggerDefinition<TInputs extends Inputs = Inputs, TConfigVars extends ConfigVarResultCollection = ConfigVarResultCollection, TPayload extends TriggerPayload = TriggerPayload, TAllowsBranching extends boolean = boolean, TResult extends TriggerResult<TAllowsBranching, TPayload> = TriggerResult<TAllowsBranching, TPayload>, TActionInputs extends Inputs = Inputs, TAction extends ActionDefinition<TActionInputs> = ActionDefinition<TActionInputs>, TCombinedInputs extends TInputs & TActionInputs = TInputs & TActionInputs> {
+export type PollingTriggerDefinition<TInputs extends Inputs = Inputs, TConfigVars extends ConfigVarResultCollection = ConfigVarResultCollection, TPayload extends TriggerPayload = TriggerPayload, TAllowsBranching extends boolean = boolean, TResult extends TriggerResult<TAllowsBranching, TPayload> = TriggerResult<TAllowsBranching, TPayload>, TActionInputs extends Inputs = Inputs, TAction extends ActionDefinition<TActionInputs> = ActionDefinition<TActionInputs>, TCombinedInputs extends TInputs & TActionInputs = TInputs & TActionInputs> = PollingTriggerDefinitionBase<TInputs, TConfigVars, TPayload, TAllowsBranching, TResult, TActionInputs, TAction, TCombinedInputs> & TriggerResolverDecl<TConfigVars, TPayload>;
+interface PollingTriggerDefinitionBase<TInputs extends Inputs = Inputs, TConfigVars extends ConfigVarResultCollection = ConfigVarResultCollection, TPayload extends TriggerPayload = TriggerPayload, TAllowsBranching extends boolean = boolean, TResult extends TriggerResult<TAllowsBranching, TPayload> = TriggerResult<TAllowsBranching, TPayload>, TActionInputs extends Inputs = Inputs, TAction extends ActionDefinition<TActionInputs> = ActionDefinition<TActionInputs>, TCombinedInputs extends TInputs & TActionInputs = TInputs & TActionInputs> {
     triggerType?: "polling";
     /** Defines how the Action is displayed in the Prismatic interface. */
     display: ActionDisplayDefinition;
@@ -39,3 +44,4 @@ export interface PollingTriggerDefinition<TInputs extends Inputs = Inputs, TConf
     examplePayload?: Awaited<ReturnType<this["perform"]>>;
 }
 export declare const isPollingTriggerDefinition: (ref: unknown) => ref is PollingTriggerDefinition;
+export {};

package/dist/types/TriggerDefinition.d.ts

@@ -1,18 +1,51 @@
+import type { ActionContext } from "./ActionPerformFunction";
 import type { ActionDisplayDefinition } from "./DisplayDefinition";
 import type { ConfigVarResultCollection, Inputs } from "./Inputs";
 import type { TriggerEventFunction } from "./TriggerEventFunction";
 import type { TriggerPayload } from "./TriggerPayload";
 import type { TriggerPerformFunction } from "./TriggerPerformFunction";
-import type { TriggerResult } from "./TriggerResult";
+import type { TriggerBaseResult, TriggerResult } from "./TriggerResult";
+/**
+ * Encodes the relationship between `triggerResolverSupport` and `triggerResolver`:
+ * - absent or `"invalid"`: no resolver allowed
+ * - `"valid"`: resolver optional
+ * - `"required"`: resolver required
+ */
+export type TriggerResolverDecl<TConfigVars extends ConfigVarResultCollection, TPayload extends TriggerPayload> = {
+    triggerResolverSupport?: "invalid" | undefined;
+    triggerResolver?: undefined;
+} | {
+    triggerResolverSupport: "valid";
+    triggerResolver?: TriggerResolver<TConfigVars, TPayload>;
+} | {
+    triggerResolverSupport: "required";
+    triggerResolver: TriggerResolver<TConfigVars, TPayload>;
+};
 declare const optionChoices: readonly ["invalid", "valid", "required"];
 export type TriggerOptionChoice = (typeof optionChoices)[number];
 export declare const TriggerOptionChoices: TriggerOptionChoice[];
+export interface TriggerResolver<TConfigVars extends ConfigVarResultCollection = ConfigVarResultCollection, TPayload extends TriggerPayload = TriggerPayload, TItem = unknown> {
+    /** Author-declared defaults for how this trigger's items are batched. */
+    default: {
+        /** Number of items per batch. Must be an integer >= 1. `1` dispatches each item individually; `>1` groups items into batches. */
+        batchSize: number;
+    };
+    /** Extracts an array of items from the trigger result for batched dispatch. Receives the same context as the trigger's perform function. */
+    resolveItems?: (context: ActionContext<TConfigVars>, result: TriggerBaseResult<TPayload>) => TItem[];
+    /** Extracts data from the trigger result to be passed to the next trigger invocation to fetch another page of data. */
+    getNextDiscoveryState?: (context: ActionContext<TConfigVars>, result: TriggerBaseResult<TPayload>) => Record<string, unknown> | null;
+}
 /**
  * TriggerDefinition is the type of the object that is passed in to `trigger` function to
  * define a component trigger. See
  * https://prismatic.io/docs/custom-connectors/triggers/
+ *
+ * Composed from `TriggerDefinitionBase` (static fields) plus the discriminated union
+ * `TriggerResolverDecl`, which enforces the resolver support relationship at the type
+ * level.
  */
-export interface TriggerDefinition<TInputs extends Inputs = Inputs, TConfigVars extends ConfigVarResultCollection = ConfigVarResultCollection, TAllowsBranching extends boolean = boolean, TResult extends TriggerResult<TAllowsBranching, TriggerPayload> = TriggerResult<TAllowsBranching, TriggerPayload>> {
+export type TriggerDefinition<TInputs extends Inputs = Inputs, TConfigVars extends ConfigVarResultCollection = ConfigVarResultCollection, TAllowsBranching extends boolean = boolean, TResult extends TriggerResult<TAllowsBranching, TriggerPayload> = TriggerResult<TAllowsBranching, TriggerPayload>> = TriggerDefinitionBase<TInputs, TConfigVars, TAllowsBranching, TResult> & TriggerResolverDecl<TConfigVars, TriggerPayload>;
+interface TriggerDefinitionBase<TInputs extends Inputs = Inputs, TConfigVars extends ConfigVarResultCollection = ConfigVarResultCollection, TAllowsBranching extends boolean = boolean, TResult extends TriggerResult<TAllowsBranching, TriggerPayload> = TriggerResult<TAllowsBranching, TriggerPayload>> {
     /** Defines how the trigger is displayed in the Prismatic UI. */
     display: ActionDisplayDefinition;
     /** Function to perform when this trigger is invoked. */

package/dist/types/TriggerPayload.d.ts

@@ -3,8 +3,13 @@ import type { FlowAttributes } from "./FlowAttributes";
 import type { InstanceAttributes } from "./InstanceAttributes";
 import type { IntegrationAttributes } from "./IntegrationAttributes";
 import type { UserAttributes } from "./UserAttributes";
-/** Represents a Trigger Payload, which is data passed into a Trigger to invoke an Integration execution. */
-export interface TriggerPayload {
+/** Represents a Trigger Payload, which is data passed into a Trigger to invoke an Integration execution.
+ *
+ * The optional `TDiscoveryState` parameter types the `discoveryState` field, so authors who
+ * declare a pagination-state shape on their `getNextDiscoveryState` resolver can read back
+ * the same shape on the next round's payload. Defaults to `Record<string, unknown>`.
+ */
+export interface TriggerPayload<TDiscoveryState extends Record<string, unknown> = Record<string, unknown>> {
     /** The headers sent in the webhook request. */
     headers: {
         [key: string]: string;
@@ -50,4 +55,8 @@ export interface TriggerPayload {
     startedAt: string;
     /** Determines whether the execution will run in debug mode. */
     globalDebug: boolean;
+    /** Managed by the execution when this trigger invocation is a paginated re-run.
+     *  Contains the object returned by `getNextDiscoveryState` from the previous round.
+     *  Absent on the initial invocation. */
+    discoveryState?: TDiscoveryState;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prismatic-io/spectral",
-  "version": "10.18.7-preview.3",
+  "version": "10.18.7-preview.5",
   "description": "Utility library for building Prismatic connectors and code-native integrations",
   "keywords": [
     "prismatic"