@prismatic-io/spectral 10.18.7-preview.4 → 10.18.7-preview.6

package/dist/index.d.ts

@@ -5,7 +5,7 @@
  */
 import { convertComponent } from "./serverTypes/convertComponent";
 import { convertIntegration } from "./serverTypes/convertIntegration";
-import type { ActionDefinition, ActionPerformReturn, ComponentDefinition, ComponentManifest, ConfigPage, ConfigVarResultCollection, ConnectionConfigVar, CustomerActivatedConnectionConfigVar, DataSourceConfigVar, DataSourceDefinition, DataSourceType, DefaultConnectionDefinition, DynamicObjectInputField, Flow, InputFieldDefinition, Inputs, IntegrationDefinition, OAuth2ConnectionDefinition, OnPremConnectionDefinition, OrganizationActivatedConnectionConfigVar, StandardConfigVar, StructuredObjectInputField, TriggerDefinition, TriggerPayload, TriggerResult } from "./types";
+import type { ActionDefinition, ActionPerformReturn, ComponentDefinition, ComponentManifest, ConfigPage, ConfigVarResultCollection, ConfigVars, ConnectionConfigVar, CustomerActivatedConnectionConfigVar, DataSourceConfigVar, DataSourceDefinition, DataSourceType, DefaultConnectionDefinition, DynamicObjectInputField, Flow, InputFieldDefinition, Inputs, IntegrationDefinition, OAuth2ConnectionDefinition, OnPremConnectionDefinition, OrganizationActivatedConnectionConfigVar, StandardConfigVar, StructuredObjectInputField, TriggerDefinition, TriggerPayload, TriggerResolverBehavior, TriggerResult } from "./types";
 import type { PollingTriggerDefinition } from "./types/PollingTriggerDefinition";
 /**
  * This function creates a code-native integration object that can be
@@ -73,7 +73,48 @@ export declare const integration: <TInputs extends Inputs, TActionInputs extends
  *   },
  * });
  */
-export declare const flow: <TInputs extends Inputs, TActionInputs extends Inputs, TPayload extends TriggerPayload = TriggerPayload, TAllowsBranching extends boolean = boolean, TResult extends TriggerResult<TAllowsBranching, TPayload> = TriggerResult<TAllowsBranching, TPayload>, TTriggerPayload extends TriggerPayload = TriggerPayload, T extends Flow<TInputs, TActionInputs, TPayload, TAllowsBranching, TResult, TTriggerPayload> = Flow<TInputs, TActionInputs, TPayload, TAllowsBranching, TResult, TTriggerPayload>>(definition: T) => T;
+export declare const flow: <TInputs extends Inputs, TActionInputs extends Inputs, TPayload extends TriggerPayload = TriggerPayload, TAllowsBranching extends boolean = boolean, TResult extends TriggerResult<TAllowsBranching, TPayload> = TriggerResult<TAllowsBranching, TPayload>, TTriggerPayload extends TriggerPayload = TriggerPayload, TItem = unknown, TDiscoveryState extends Record<string, unknown> = Record<string, unknown>, T extends Flow<TInputs, TActionInputs, TPayload, TAllowsBranching, TResult, TTriggerPayload, TItem, TDiscoveryState> = Flow<TInputs, TActionInputs, TPayload, TAllowsBranching, TResult, TTriggerPayload, TItem, TDiscoveryState>>(definition: T & {
+    triggerResolver?: TriggerResolverBehavior<ConfigVars, TriggerPayload, TItem, TDiscoveryState>;
+    onDeployResolver?: TriggerResolverBehavior<ConfigVars, TriggerPayload, TItem, TDiscoveryState>;
+}) => T;
+/**
+ * Builds a flow's `triggerResolver` — the behavior that extracts the records a trigger
+ * returns into batched dispatches and (optionally) paginates. Batch *sizing* comes from
+ * the flow's `batch` config, not from here. Supply the item and pagination-cursor types
+ * explicitly — `triggerResolver<Order, { cursor: number }>({ ... })` — and they flow
+ * through the whole chain: `resolveItems` returns `Order[]`, `result.payload.discoveryState`
+ * reads back as `{ cursor: number }`, and the flow's `onExecution` sees
+ * `params.onTrigger.results.body.data` typed as `Order | Order[]`.
+ *
+ * @typeParam TItem - the item type each batched execution receives.
+ * @typeParam TDiscoveryState - the pagination cursor shape round-tripped via `payload.discoveryState`.
+ * @see {@link https://prismatic.io/docs/integrations/code-native/flows/ | Code-Native Flows}
+ * @example
+ * import { flow, triggerResolver } from "@prismatic-io/spectral";
+ *
+ * flow({
+ *   // ...
+ *   batch: { batchSize: 50 },
+ *   triggerResolver: triggerResolver<Order, { cursor: number }>({
+ *     resolveItems: (context, result) => result.payload.body.data as Order[],
+ *     getNextDiscoveryState: (context, result) => {
+ *       const next = result.payload.discoveryState?.cursor; // number | undefined
+ *       return next === undefined ? null : { cursor: next };
+ *     },
+ *   }),
+ * });
+ */
+export declare const triggerResolver: <TItem = unknown, TDiscoveryState extends Record<string, unknown> = Record<string, unknown>, TConfigVars extends ConfigVarResultCollection = ConfigVars, TPayload extends TriggerPayload = TriggerPayload>(resolver: TriggerResolverBehavior<TConfigVars, TPayload, TItem, TDiscoveryState>) => TriggerResolverBehavior<TConfigVars, TPayload, TItem, TDiscoveryState>;
+/**
+ * Builds a flow's `onDeployResolver` — the resolver behavior for the `onDeployTrigger`
+ * fire that runs once when an instance is first deployed. Identical in shape to
+ * {@link triggerResolver} and shares the flow's `batch` config; named separately so the
+ * call site reads as the sibling of `onDeployTrigger`.
+ *
+ * @typeParam TItem - the item type each batched on-deploy execution receives.
+ * @typeParam TDiscoveryState - the pagination cursor shape round-tripped via `payload.discoveryState`.
+ */
+export declare const onDeployResolver: <TItem = unknown, TDiscoveryState extends Record<string, unknown> = Record<string, unknown>, TConfigVars extends ConfigVarResultCollection = ConfigVars, TPayload extends TriggerPayload = TriggerPayload>(resolver: TriggerResolverBehavior<TConfigVars, TPayload, TItem, TDiscoveryState>) => TriggerResolverBehavior<TConfigVars, TPayload, TItem, TDiscoveryState>;
 /**
  * This function creates a config wizard page object for use in code-native
  * integrations.

package/dist/index.js

@@ -22,7 +22,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.util = exports.testing = exports.componentManifests = exports.oauth2Connection = exports.onPremConnection = exports.connection = exports.dynamicObjectInput = exports.structuredObjectInput = 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.dynamicObjectInput = exports.structuredObjectInput = 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.onDeployResolver = exports.triggerResolver = exports.flow = exports.integration = void 0;
 const serverTypes_1 = require("./serverTypes");
 const convertComponent_1 = require("./serverTypes/convertComponent");
 const convertIntegration_1 = require("./serverTypes/convertIntegration");
@@ -102,8 +102,53 @@ exports.integration = integration;
  *   },
  * });
  */
-const flow = (definition) => definition;
+const flow = (
+// The intersection adds an explicit inference site for `TItem`/`TDiscoveryState`
+// (from the resolver's `resolveItems` / `getNextDiscoveryState` return types) that
+// the `T extends Flow<...>` capture alone does not provide, while `T` still preserves
+// the precise literal type for the return value.
+definition) => definition;
 exports.flow = flow;
+/**
+ * Builds a flow's `triggerResolver` — the behavior that extracts the records a trigger
+ * returns into batched dispatches and (optionally) paginates. Batch *sizing* comes from
+ * the flow's `batch` config, not from here. Supply the item and pagination-cursor types
+ * explicitly — `triggerResolver<Order, { cursor: number }>({ ... })` — and they flow
+ * through the whole chain: `resolveItems` returns `Order[]`, `result.payload.discoveryState`
+ * reads back as `{ cursor: number }`, and the flow's `onExecution` sees
+ * `params.onTrigger.results.body.data` typed as `Order | Order[]`.
+ *
+ * @typeParam TItem - the item type each batched execution receives.
+ * @typeParam TDiscoveryState - the pagination cursor shape round-tripped via `payload.discoveryState`.
+ * @see {@link https://prismatic.io/docs/integrations/code-native/flows/ | Code-Native Flows}
+ * @example
+ * import { flow, triggerResolver } from "@prismatic-io/spectral";
+ *
+ * flow({
+ *   // ...
+ *   batch: { batchSize: 50 },
+ *   triggerResolver: triggerResolver<Order, { cursor: number }>({
+ *     resolveItems: (context, result) => result.payload.body.data as Order[],
+ *     getNextDiscoveryState: (context, result) => {
+ *       const next = result.payload.discoveryState?.cursor; // number | undefined
+ *       return next === undefined ? null : { cursor: next };
+ *     },
+ *   }),
+ * });
+ */
+const triggerResolver = (resolver) => resolver;
+exports.triggerResolver = triggerResolver;
+/**
+ * Builds a flow's `onDeployResolver` — the resolver behavior for the `onDeployTrigger`
+ * fire that runs once when an instance is first deployed. Identical in shape to
+ * {@link triggerResolver} and shares the flow's `batch` config; named separately so the
+ * call site reads as the sibling of `onDeployTrigger`.
+ *
+ * @typeParam TItem - the item type each batched on-deploy execution receives.
+ * @typeParam TDiscoveryState - the pagination cursor shape round-tripped via `payload.discoveryState`.
+ */
+const onDeployResolver = (resolver) => resolver;
+exports.onDeployResolver = onDeployResolver;
 /**
  * This function creates a config wizard page object for use in code-native
  * integrations.

package/dist/serverTypes/convertComponent.d.ts

@@ -7,6 +7,18 @@ 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 the
+ * component-trigger (`TriggerDefinition.batch.batchSize`) and CNI flow (`flow.batch.batchSize`)
+ * validation paths.
+ */
+export declare const validateBatchSize: (ownerLabel: string, fieldName: string, batchSize: unknown) => number;
+/**
+ * Throws if `concurrentBatchLimit` is set but isn't a positive integer; returns it
+ * unchanged (including `undefined`, which the platform treats as unlimited). Shared by the
+ * component-trigger and CNI flow paths, both sourcing it from the single `batchConfig`.
+ */
+export declare const validateConcurrentBatchLimit: (ownerLabel: string, fieldName: string, concurrentBatchLimit: unknown) => number | undefined;
 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.validateConcurrentBatchLimit = 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,87 @@ 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 the
+ * component-trigger (`TriggerDefinition.batch.batchSize`) and CNI flow (`flow.batch.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;
+/**
+ * Throws if `concurrentBatchLimit` is set but isn't a positive integer; returns it
+ * unchanged (including `undefined`, which the platform treats as unlimited). Shared by the
+ * component-trigger and CNI flow paths, both sourcing it from the single `batchConfig`.
+ */
+const validateConcurrentBatchLimit = (ownerLabel, fieldName, concurrentBatchLimit) => {
+    if (concurrentBatchLimit === undefined) {
+        return undefined;
+    }
+    if (typeof concurrentBatchLimit !== "number" ||
+        !Number.isInteger(concurrentBatchLimit) ||
+        concurrentBatchLimit < 1) {
+        throw new Error(`${ownerLabel} has an invalid ${fieldName} concurrentBatchLimit of ${String(concurrentBatchLimit)}. concurrentBatchLimit must be an integer >= 1.`);
+    }
+    return concurrentBatchLimit;
+};
+exports.validateConcurrentBatchLimit = validateConcurrentBatchLimit;
+/**
+ * Emits the trigger's single default batch size to the one wire field the platform reads
+ * (`triggerResolverDefaultBatchSize`), shared by both the trigger and on-deploy resolution.
+ * Emitted when the trigger declares a resolver — `triggerResolverSupport` `"valid"`/`"required"`
+ * for the normal path, or an `onDeployResolver` for the on-deploy path. Defaults to 1 when no
+ * `batchConfig` was declared.
+ */
+const buildBatchDefaultField = (triggerLabel, triggerResolverSupport, hasOnDeployResolver, batchConfig) => {
+    if (triggerResolverSupport === "invalid" && !hasOnDeployResolver) {
+        return {};
+    }
+    const concurrentBatchLimit = batchConfig
+        ? (0, exports.validateConcurrentBatchLimit)(`Trigger "${triggerLabel}"`, "batchConfig", batchConfig.concurrentBatchLimit)
+        : undefined;
+    return Object.assign({ triggerResolverDefaultBatchSize: batchConfig
+            ? (0, exports.validateBatchSize)(`Trigger "${triggerLabel}"`, "batchConfig", batchConfig.batchSize)
+            : 1 }, (concurrentBatchLimit !== undefined
+        ? { triggerResolverDefaultConcurrentBatchLimit: concurrentBatchLimit }
+        : {}));
+};
+const buildTriggerResolverFields = (resolver) => {
+    if (!resolver) {
+        return {};
+    }
+    return Object.assign(Object.assign({}, (resolver.resolveItems
+        ? {
+            resolveTriggerItems: resolver.resolveItems,
+            hasResolveTriggerItems: true,
+        }
+        : {})), (resolver.getNextDiscoveryState
+        ? {
+            getNextDiscoveryState: resolver.getNextDiscoveryState,
+            hasGetNextDiscoveryState: true,
+        }
+        : {}));
+};
+const buildOnDeployResolverFields = (resolver) => {
+    if (!resolver) {
+        return {};
+    }
+    return Object.assign(Object.assign({}, (resolver.resolveItems
+        ? {
+            resolveOnDeployItems: resolver.resolveItems,
+            hasResolveOnDeployItems: true,
+        }
+        : {})), (resolver.getNextDiscoveryState
+        ? {
+            getOnDeployNextDiscoveryState: resolver.getNextDiscoveryState,
+            hasGetOnDeployNextDiscoveryState: 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"]);
@@ -132,7 +213,14 @@ const convertAction = (actionKey, _a, hooks) => {
             errorHandler: hooks === null || hooks === void 0 ? void 0 : hooks.error,
         }) });
 };
-const convertTrigger = (triggerKey, trigger, hooks) => {
+const convertTrigger = (triggerKey, 
+// `any` is load-bearing: the user-facing TriggerDefinition / PollingTriggerDefinition
+// type their event-function fields (onInstanceDeploy, webhookLifecycleHandlers, etc.) over
+// TInputs/TConfigVars/TPayload, while the wire-format ServerTrigger drops those generics.
+// The `...trigger` spread in the result construction below would surface variance errors
+// without these `any`s. The user-typed handlers are immediately replaced with
+// createPerform-wrapped versions, so the loose input typing is safe in practice.
+trigger, hooks) => {
     var _a;
     const { onInstanceDeploy, onInstanceDelete } = trigger;
     const webhookLifecycleHandlers = "webhookLifecycleHandlers" in trigger ? trigger.webhookLifecycleHandlers : undefined;
@@ -143,6 +231,26 @@ 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 batchConfig = "batchConfig" in trigger ? trigger.batchConfig : undefined;
+    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".`);
+    }
+    const onDeployPerform = "onDeployPerform" in trigger ? trigger.onDeployPerform : undefined;
+    const onDeployResolver = "onDeployResolver" in trigger ? trigger.onDeployResolver : undefined;
+    // On-deploy is presence-driven (no support flag): a trigger that defines an
+    // `onDeployResolver` must also define the `onDeployPerform` fire it batches.
+    if ((onDeployResolver === null || onDeployResolver === void 0 ? void 0 : onDeployResolver.resolveItems) && !onDeployPerform) {
+        throw new Error(`Trigger "${trigger.display.label}" declares onDeployResolver.resolveItems but is missing onDeployPerform.`);
+    }
     let convertedActionInputs = [];
     let performToUse;
     if ((0, PollingTriggerDefinition_1.isPollingTriggerDefinition)(trigger)) {
@@ -171,11 +279,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(Object.assign(Object.assign({}, (0, omit_1.default)(trigger, ["batchConfig", "triggerResolver", "onDeployResolver"])), { 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 }), buildBatchDefaultField(trigger.display.label, triggerResolverSupport, !!(onDeployResolver === null || onDeployResolver === void 0 ? void 0 : onDeployResolver.resolveItems), batchConfig)), buildTriggerResolverFields(triggerResolver)), buildOnDeployResolverFields(onDeployResolver)), ((0, PollingTriggerDefinition_1.isPollingTriggerDefinition)(trigger) ? { isPollingTrigger: true } : {}));
     if (onInstanceDeploy) {
         result.onInstanceDeploy = (0, perform_1.createPerform)(onInstanceDeploy, {
             inputCleaners: triggerInputCleaners,
@@ -183,6 +291,13 @@ const convertTrigger = (triggerKey, trigger, hooks) => {
         });
         result.hasOnInstanceDeploy = true;
     }
+    if (onDeployPerform) {
+        result.onDeployPerform = (0, perform_1.createPerform)(onDeployPerform, {
+            inputCleaners: triggerInputCleaners,
+            errorHandler: hooks === null || hooks === void 0 ? void 0 : hooks.error,
+        });
+        result.hasOnDeployPerform = true;
+    }
     if (onInstanceDelete) {
         result.onInstanceDelete = (0, perform_1.createPerform)(onInstanceDelete, {
             inputCleaners: triggerInputCleaners,

package/dist/serverTypes/convertIntegration.js

@@ -319,6 +319,7 @@ const convertFlow = (flow, componentRegistry, referenceKey) => {
     result.onInstanceDelete = undefined;
     result.webhookLifecycleHandlers = undefined;
     result.onExecution = undefined;
+    result.onDeployTrigger = undefined;
     result.preprocessFlowConfig = undefined;
     result.errorConfig = undefined;
     result.testApiKeys = undefined;
@@ -403,6 +404,30 @@ const convertFlow = (flow, componentRegistry, referenceKey) => {
             }
             : {}));
     }
+    const triggerResolver = "triggerResolver" in flow ? flow.triggerResolver : undefined;
+    const onDeployResolver = "onDeployResolver" in flow ? flow.onDeployResolver : undefined;
+    const batchConfig = "batchConfig" in flow ? flow.batchConfig : undefined;
+    // Resolver behaviors (resolveItems/getNextDiscoveryState) are serialized onto the
+    // synthesized trigger below. On the flow wire we emit only `triggerResolver`, the single
+    // config the platform reads (`trigger_resolver_batch_size` / `trigger_resolver_enabled`)
+    // and shares between the normal and on-deploy fires. `batchConfig`/`onDeployResolver` are
+    // author-side only — clear them out of the `{ ...flow }` spread.
+    result.triggerResolver = undefined;
+    result.onDeployResolver = undefined;
+    result.batchConfig = undefined;
+    if (triggerResolver || onDeployResolver) {
+        if (!batchConfig) {
+            throw new Error(`${flow.name} defines a triggerResolver/onDeployResolver but no batchConfig. Add \`batchConfig: { batchSize }\` to the flow.`);
+        }
+        if (onDeployResolver &&
+            (!("onDeployTrigger" in flow) || typeof flow.onDeployTrigger !== "function")) {
+            throw new Error(`${flow.name} declares onDeployResolver without onDeployTrigger. Set onDeployTrigger to handle the initial-deploy fire that the resolver fans out.`);
+        }
+        // `enabled: true` is required: for a "valid"-support trigger (which CNI synthesized
+        // triggers are) the platform only batches when the flow's resolver is enabled.
+        const concurrentBatchLimit = (0, convertComponent_1.validateConcurrentBatchLimit)(flow.name, "batchConfig", batchConfig.concurrentBatchLimit);
+        result.triggerResolver = Object.assign({ batchSize: (0, convertComponent_1.validateBatchSize)(flow.name, "batchConfig", batchConfig.batchSize), enabled: true }, (concurrentBatchLimit !== undefined ? { concurrentBatchLimit } : {}));
+    }
     const actionStep = {
         action: {
             key: flowFunctionKey(flow.name, "onExecution"),
@@ -670,7 +695,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 +768,8 @@ 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, batchConfig, triggerResolver, onDeployTrigger, onDeployResolver, }) => {
+        var _a;
         if (!flowUsesWrapperTrigger({
             onTrigger,
             onInstanceDelete,
@@ -774,26 +804,45 @@ 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(Object.assign(Object.assign(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 || onDeployResolver
+                ? Object.assign({ triggerResolverDefaultBatchSize: (_a = batchConfig === null || batchConfig === void 0 ? void 0 : batchConfig.batchSize) !== null && _a !== void 0 ? _a : 1 }, ((batchConfig === null || batchConfig === void 0 ? void 0 : batchConfig.concurrentBatchLimit) !== undefined
+                    ? {
+                        triggerResolverDefaultConcurrentBatchLimit: batchConfig.concurrentBatchLimit,
+                    }
+                    : {})) : {})), (triggerResolver
+                ? Object.assign(Object.assign({}, (triggerResolver.resolveItems
+                    ? {
+                        resolveTriggerItems: triggerResolver.resolveItems,
+                        hasResolveTriggerItems: true,
+                    }
+                    : {})), (triggerResolver.getNextDiscoveryState
+                    ? {
+                        getNextDiscoveryState: triggerResolver.getNextDiscoveryState,
+                        hasGetNextDiscoveryState: true,
+                    }
+                    : {})) : {})), (onDeployTrigger
+                ? {
+                    onDeployPerform: (0, perform_1.createCNIPerform)({
+                        componentRegistry,
+                        onTrigger: onDeployTrigger,
+                    }),
+                    hasOnDeployPerform: true,
+                }
+                : {})), (onDeployResolver
+                ? Object.assign(Object.assign({}, (onDeployResolver.resolveItems
+                    ? {
+                        resolveOnDeployItems: onDeployResolver.resolveItems,
+                        hasResolveOnDeployItems: true,
+                    }
+                    : {})), (onDeployResolver.getNextDiscoveryState
+                    ? {
+                        getOnDeployNextDiscoveryState: onDeployResolver.getNextDiscoveryState,
+                        hasGetOnDeployNextDiscoveryState: 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,23 @@ 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.
+ *
+ * The on-deploy fire is named asymmetrically by intent: CNI flow authors set
+ * `onDeployTrigger` (sibling to `onTrigger`), component-trigger authors set
+ * `onDeployPerform` (sibling to `perform`), and both flatten to
+ * `onDeployPerform` here on the wire.
+ */
 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 +166,23 @@ export interface Trigger<TInputs extends Inputs, TActionInputs extends Inputs, T
     hasWebhookDeleteFunction?: boolean;
     scheduleSupport: TriggerOptionChoice;
     synchronousResponseSupport: TriggerOptionChoice;
+    triggerResolverSupport?: TriggerOptionChoice;
+    /**
+     * The single default batch size shared by the trigger and on-deploy resolvers. The
+     * platform reads only this field for both paths; there is no separate on-deploy default.
+     */
+    triggerResolverDefaultBatchSize?: number;
+    triggerResolverDefaultConcurrentBatchLimit?: number;
+    resolveTriggerItems?: (context: ActionContext<TConfigVars>, result: TriggerBaseResult<TPayload>) => unknown[];
+    hasResolveTriggerItems?: boolean;
+    getNextDiscoveryState?: (context: ActionContext<TConfigVars>, result: TriggerBaseResult<TPayload>) => Record<string, unknown> | null;
+    hasGetNextDiscoveryState?: boolean;
+    onDeployPerform?: TriggerPerformFunction<TInputs, TConfigVars, TAllowsBranching, TResult> | PollingTriggerPerformFunction<TInputs, TActionInputs, TConfigVars, TPayload, TAllowsBranching, TResult> | CNIPollingPerformFunction<TInputs, TConfigVars, TPayload, TAllowsBranching> | ComponentRefTriggerPerformFunction<TInputs, TConfigVars>;
+    hasOnDeployPerform?: boolean;
+    resolveOnDeployItems?: (context: ActionContext<TConfigVars>, result: TriggerBaseResult<TPayload>) => unknown[];
+    hasResolveOnDeployItems?: boolean;
+    getOnDeployNextDiscoveryState?: (context: ActionContext<TConfigVars>, result: TriggerBaseResult<TPayload>) => Record<string, unknown> | null;
+    hasGetOnDeployNextDiscoveryState?: boolean;
     examplePayload?: unknown;
     isCommonTrigger?: boolean;
     isPollingTrigger?: boolean;

package/dist/testing.d.ts

@@ -217,7 +217,7 @@ type ToTestValues<TConfigVars extends ConfigVarResultCollection> = {
  *   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, }?: {
+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, any, any, any>, { configVars, context, payload, }?: {
     configVars?: TConfigVarValues;
     context?: Partial<ActionContext<TConfigVars>>;
     payload?: Partial<TriggerPayload>;

package/dist/testing.js

@@ -408,7 +408,11 @@ const createConfigVars = (values) => {
  *   expect(result.data).toBeDefined();
  * });
  */
-const invokeFlow = (flow_1, ...args_1) => __awaiter(void 0, [flow_1, ...args_1], void 0, function* (flow, { configVars, context, payload, } = {}) {
+const invokeFlow = (flow_1, ...args_1) => __awaiter(void 0, [flow_1, ...args_1], void 0, function* (
+// `any` for TItem/TDiscoveryState/TTriggerPayload: the tester accepts a flow with any
+// resolver item and cursor typing; it drives the flow dynamically and does not rely on
+// the precise `onExecution` param type.
+flow, { configVars, context, payload, } = {}) {
     const realizedConfigVars = createConfigVars(configVars);
     const realizedContext = createActionContext(Object.assign(Object.assign({}, context), { configVars: realizedConfigVars }));
     const realizedPayload = Object.assign(Object.assign({}, (0, exports.defaultTriggerPayload)()), payload);

package/dist/types/IntegrationDefinition.d.ts

@@ -7,6 +7,7 @@ import type { FlowDefinitionFlowSchema } from "./FlowSchemas";
 import type { Inputs } from "./Inputs";
 import type { PollingTriggerPerformFunction } from "./PollingTriggerDefinition";
 import type { ScopedConfigVarMap } from "./ScopedConfigVars";
+import type { BatchConfig, TriggerResolverBehavior } from "./TriggerDefinition";
 import type { TriggerEventFunction } from "./TriggerEventFunction";
 import type { TriggerPayload } from "./TriggerPayload";
 import type { TriggerPerformFunction } from "./TriggerPerformFunction";
@@ -46,8 +47,13 @@ export type IntegrationDefinition<TInputs extends Inputs = Inputs, TActionInputs
     /**
      * Flows for this integration. See
      * https://prismatic.io/docs/integrations/code-native/flows/
+     *
+     * The trailing `any`s for `TItem`/`TDiscoveryState`/`TTriggerPayload` let flows with
+     * different resolver item and cursor types live in one array. `integration` only holds
+     * and serializes these flows (it never invokes `onExecution`), so the precise — and
+     * per-flow distinct — `onExecution` param type does not need to be preserved here.
      */
-    flows: Flow<TInputs, TActionInputs, TPayload, TAllowsBranching, TResult>[];
+    flows: Flow<TInputs, TActionInputs, TPayload, TAllowsBranching, TResult, any, any, any>[];
     /**
      * Config wizard pages for this integration. See
      * https://prismatic.io/docs/integrations/code-native/config-wizard/
@@ -70,12 +76,24 @@ export type IntegrationDefinition<TInputs extends Inputs = Inputs, TActionInputs
      */
     componentRegistry?: ComponentRegistry;
 };
-export type FlowOnExecution<TTriggerPayload extends TriggerPayload> = ActionPerformFunction<{
+/**
+ * The trigger payload as `onExecution` sees it. When a `triggerResolver` is in
+ * play, the platform replaces `body.data` with this execution's batch slice —
+ * a single `TItem` when `batchSize` is 1, otherwise a `TItem[]`. When no item
+ * type is known (`TItem` defaults to `unknown`), the payload is left untouched.
+ */
+export type BatchedTriggerPayload<TPayload extends TriggerPayload, TItem> = unknown extends TItem ? TPayload : Omit<TPayload, "body"> & {
+    body: {
+        data: TItem | TItem[];
+        contentType?: string;
+    };
+};
+export type FlowOnExecution<TTriggerPayload extends TriggerPayload, TItem = unknown> = ActionPerformFunction<{
     onTrigger: {
         type: "data";
         label: string;
         clean: (value: unknown) => {
-            results: TTriggerPayload;
+            results: BatchedTriggerPayload<TTriggerPayload, TItem>;
         };
     };
 }, ConfigVars, {
@@ -86,7 +104,7 @@ export type FlowExecutionContext = ActionContext<ConfigVars, {
 }>;
 export type FlowExecutionContextActions = FlowExecutionContext["components"];
 /** Base properties shared by all flow types. */
-interface FlowBase<TTriggerPayload extends TriggerPayload = TriggerPayload> {
+interface FlowBase<TTriggerPayload extends TriggerPayload = TriggerPayload, TItem = unknown, TDiscoveryState extends Record<string, unknown> = Record<string, unknown>> {
     /** The unique name for this flow. */
     name: string;
     /** A unique, unchanging value that is used to maintain identity for the flow even if the name changes. */
@@ -117,6 +135,25 @@ interface FlowBase<TTriggerPayload extends TriggerPayload = TriggerPayload> {
      */
     organizationApiKeys?: string[];
     testApiKeys?: string[];
+    /**
+     * Batch-dispatch config for this flow's resolvers. A single config shared by both
+     * `triggerResolver` and `onDeployResolver` — they always batch the same way. For a
+     * CNI flow this value is authoritative (what's written here is what's used). Required
+     * whenever the flow defines a `triggerResolver` or `onDeployResolver`.
+     */
+    batchConfig?: BatchConfig;
+    /**
+     * Trigger resolver behavior: extracts the items returned by the trigger into batched
+     * dispatches and (optionally) paginates. Sizing comes from the flow's `batchConfig`.
+     * When using an existing component trigger, that trigger must declare
+     * `triggerResolverSupport`; CNI flows infer support from the resolver's presence.
+     */
+    triggerResolver?: TriggerResolverBehavior<ConfigVars, TriggerPayload, TItem, TDiscoveryState>;
+    /**
+     * On-deploy resolver behavior: same as `triggerResolver` but for the `onDeployTrigger`
+     * initial-deploy fire. Shares the flow's `batchConfig`.
+     */
+    onDeployResolver?: TriggerResolverBehavior<ConfigVars, TriggerPayload, TItem, TDiscoveryState>;
     /** Error handling configuration. */
     errorConfig?: StepErrorConfig;
     /** Optional schemas definitions for the flow. Currently only for use with AI agents. */
@@ -144,22 +181,28 @@ interface FlowBase<TTriggerPayload extends TriggerPayload = TriggerPayload> {
         delete: TriggerEventFunction<Inputs, ConfigVars>;
     };
     /** Specifies the main function for this flow which is run when this flow is invoked. */
-    onExecution: FlowOnExecution<TTriggerPayload>;
+    onExecution: FlowOnExecution<TTriggerPayload, TItem>;
 }
 export type StandardTriggerType = "standard";
 /** A standard flow with a webhook or scheduled trigger (non-polling). */
-interface StandardFlow<TInputs extends Inputs = Inputs, TPayload extends TriggerPayload = TriggerPayload, TAllowsBranching extends boolean = false, TResult extends TriggerResult<TAllowsBranching, TPayload> = TriggerResult<TAllowsBranching, TPayload>, TTriggerPayload extends TriggerPayload = TriggerPayload> extends FlowBase<TTriggerPayload> {
+interface StandardFlow<TInputs extends Inputs = Inputs, TPayload extends TriggerPayload = TriggerPayload, TAllowsBranching extends boolean = false, TResult extends TriggerResult<TAllowsBranching, TPayload> = TriggerResult<TAllowsBranching, TPayload>, TTriggerPayload extends TriggerPayload = TriggerPayload, TItem = unknown, TDiscoveryState extends Record<string, unknown> = Record<string, unknown>> extends FlowBase<TTriggerPayload, TItem, TDiscoveryState> {
     triggerType?: StandardTriggerType;
     /** Schedule configuration that defines the frequency with which this flow will be automatically executed. */
     schedule?: (ValueExpression<string> | ConfigVarExpression) & {
         timezone?: string;
     };
     /** Specifies the trigger function for this flow, which returns a payload and optional HTTP response. */
-    onTrigger?: TriggerReference | TriggerPerformFunction<TInputs, ConfigVars, TAllowsBranching, TResult>;
+    onTrigger?: TriggerReference | TriggerPerformFunction<TInputs, ConfigVars, TAllowsBranching, TResult, TDiscoveryState>;
+    /**
+     * Function to execute on initial instance deploy, in addition to (and independent of) `onTrigger`.
+     * Typically used to backfill baseline records for systems whose webhooks only emit future events.
+     * Pair with `onDeployResolver` to batch the records it returns.
+     */
+    onDeployTrigger?: TriggerPerformFunction<TInputs, ConfigVars, TAllowsBranching, TResult, TDiscoveryState>;
 }
 export type PollingTriggerType = "polling";
 /** A polling flow that runs on a schedule and has access to polling context (getState/setState). */
-interface PollingFlow<TInputs extends Inputs, TActionInputs extends Inputs, TPayload extends TriggerPayload = TriggerPayload, TAllowsBranching extends boolean = boolean, TResult extends TriggerResult<TAllowsBranching, TPayload> = TriggerResult<TAllowsBranching, TPayload>, TTriggerPayload extends TriggerPayload = TriggerPayload> extends FlowBase<TTriggerPayload> {
+interface PollingFlow<TInputs extends Inputs, TActionInputs extends Inputs, TPayload extends TriggerPayload = TriggerPayload, TAllowsBranching extends boolean = boolean, TResult extends TriggerResult<TAllowsBranching, TPayload> = TriggerResult<TAllowsBranching, TPayload>, TTriggerPayload extends TriggerPayload = TriggerPayload, TItem = unknown, TDiscoveryState extends Record<string, unknown> = Record<string, unknown>> extends FlowBase<TTriggerPayload, TItem, TDiscoveryState> {
     /**
      * Type of trigger for this flow. A "polling" trigger runs on a schedule
      * and can use context.polling.* functions. Requires schedule to be set.
@@ -173,9 +216,15 @@ interface PollingFlow<TInputs extends Inputs, TActionInputs extends Inputs, TPay
      * Specifies the trigger function for this flow.
      */
     onTrigger: PollingTriggerPerformFunction<TInputs, TActionInputs, ConfigVars, TPayload, TAllowsBranching, TResult>;
+    /**
+     * Function to execute on initial instance deploy, in addition to (and independent of) `onTrigger`.
+     * Typically used to backfill baseline records for systems whose webhooks only emit future events.
+     * Pair with `onDeployResolver` to batch the records it returns.
+     */
+    onDeployTrigger?: TriggerPerformFunction<TInputs, ConfigVars, TAllowsBranching, TResult, TDiscoveryState>;
 }
 /** Defines attributes of a flow of a code-native integration. */
-export type Flow<TInputs extends Inputs, TActionInputs extends Inputs, TPayload extends TriggerPayload = TriggerPayload, TAllowsBranching extends boolean = boolean, TResult extends TriggerResult<TAllowsBranching, TPayload> = TriggerResult<TAllowsBranching, TPayload>, TTriggerPayload extends TriggerPayload = TriggerPayload> = StandardFlow<TInputs, TPayload, TAllowsBranching, TResult, TTriggerPayload> | PollingFlow<TInputs, TActionInputs, TPayload, TAllowsBranching, TResult, TTriggerPayload>;
+export type Flow<TInputs extends Inputs, TActionInputs extends Inputs, TPayload extends TriggerPayload = TriggerPayload, TAllowsBranching extends boolean = boolean, TResult extends TriggerResult<TAllowsBranching, TPayload> = TriggerResult<TAllowsBranching, TPayload>, TTriggerPayload extends TriggerPayload = TriggerPayload, TItem = unknown, TDiscoveryState extends Record<string, unknown> = Record<string, unknown>> = StandardFlow<TInputs, TPayload, TAllowsBranching, TResult, TTriggerPayload, TItem, TDiscoveryState> | PollingFlow<TInputs, TActionInputs, TPayload, TAllowsBranching, TResult, TTriggerPayload, TItem, TDiscoveryState>;
 export type FlowTriggerType = PollingTriggerType | StandardTriggerType;
 /** Defines attributes of a Preprocess flow Configuration used by a flow of an integration. */
 export type PreprocessFlowConfig = {

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 { BatchConfig, OnDeployDecl, TriggerResolverDecl } from "./TriggerDefinition";
 import type { TriggerEventFunction } from "./TriggerEventFunction";
 import type { TriggerPayload } from "./TriggerPayload";
 import type { TriggerResult } from "./TriggerResult";
@@ -18,11 +19,21 @@ 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` (resolver support)
+ * and `OnDeployDecl` (the on-deploy perform/resolver relationship), enforced 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> & OnDeployDecl<TInputs, TConfigVars, TPayload, TAllowsBranching, TResult>;
+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;
+    /**
+     * Default batch-dispatch config shared by `triggerResolver` and `onDeployResolver`.
+     * Required when this trigger declares either (a `triggerResolver` with
+     * `triggerResolverSupport` `"valid"`/`"required"`, or an `onDeployResolver`).
+     */
+    batchConfig?: BatchConfig;
     /** Defines your trigger's polling behavior. */
     pollAction?: TAction;
     /** Function to perform when this Trigger is invoked. A default perform will be provided for most polling triggers but defining this allows for custom behavior. */
@@ -39,3 +50,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,22 +1,119 @@
+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
+ *
+ * `triggerResolver` is the resolver *behavior* only; batch sizing comes from the
+ * trigger's shared `batchConfig` (see `TriggerDefinition`).
+ */
+export type TriggerResolverDecl<TConfigVars extends ConfigVarResultCollection, TPayload extends TriggerPayload, TItem = unknown, TDiscoveryState extends Record<string, unknown> = Record<string, unknown>> = {
+    triggerResolverSupport?: "invalid" | undefined;
+    triggerResolver?: undefined;
+} | {
+    triggerResolverSupport: "valid";
+    triggerResolver?: TriggerResolverBehavior<TConfigVars, TPayload, TItem, TDiscoveryState>;
+} | {
+    triggerResolverSupport: "required";
+    triggerResolver: TriggerResolverBehavior<TConfigVars, TPayload, TItem, TDiscoveryState>;
+};
+/**
+ * Encodes the relationship between `onDeployPerform` and `onDeployResolver`. On-deploy is
+ * presence-driven — there is no separate support flag: a trigger fires on deploy if it
+ * defines `onDeployPerform`, and batches that fire if it also defines an `onDeployResolver`.
+ * An `onDeployResolver` therefore requires an `onDeployPerform`.
+ *
+ * `onDeployPerform` is the component-trigger sibling to `perform`. A CNI flow names the
+ * same on-deploy fire `onDeployTrigger` (sibling to its `onTrigger`); both flatten to
+ * `onDeployPerform` on the wire.
+ */
+export type OnDeployDecl<TInputs extends Inputs, TConfigVars extends ConfigVarResultCollection, TPayload extends TriggerPayload, TAllowsBranching extends boolean, TResult extends TriggerResult<TAllowsBranching, TPayload>, TItem = unknown, TDiscoveryState extends Record<string, unknown> = Record<string, unknown>> = {
+    onDeployPerform?: undefined;
+    onDeployResolver?: undefined;
+} | {
+    onDeployPerform: TriggerPerformFunction<TInputs, TConfigVars, TAllowsBranching, TResult>;
+    onDeployResolver?: TriggerResolverBehavior<TConfigVars, TPayload, TItem, TDiscoveryState>;
+};
 declare const optionChoices: readonly ["invalid", "valid", "required"];
 export type TriggerOptionChoice = (typeof optionChoices)[number];
 export declare const TriggerOptionChoices: TriggerOptionChoice[];
+/**
+ * The batching/pagination behavior shared by every resolver surface — component
+ * triggers (`TriggerResolver`), CNI flows (`TriggerResolverConfig`), and the
+ * on-deploy variants. Defining it once keeps the contract from drifting across
+ * those surfaces.
+ *
+ * The two type variables ARE the data that flows through the batch chain:
+ *
+ *   perform ──▶ resolveItems ──▶ [batch of TItem] ──▶ onExecution
+ *                    │
+ *                    └─ getNextDiscoveryState ──▶ payload.discoveryState ──▶ next perform
+ *
+ * @typeParam TItem - element produced by `resolveItems`. With `batchSize: 1`
+ *   each execution receives one `TItem` as its trigger data; with `batchSize > 1`
+ *   it receives a `TItem[]` slice.
+ * @typeParam TDiscoveryState - the pagination cursor. Whatever
+ *   `getNextDiscoveryState` returns is what the next round reads back on
+ *   `payload.discoveryState` (see {@link TriggerPayload}). The `result.payload`
+ *   passed to both callbacks has its `discoveryState` narrowed to this type, so
+ *   the cursor round-trip is checked end to end.
+ */
+export interface TriggerResolverBehavior<TConfigVars extends ConfigVarResultCollection = ConfigVarResultCollection, TPayload extends TriggerPayload = TriggerPayload, TItem = unknown, TDiscoveryState extends Record<string, unknown> = Record<string, unknown>> {
+    /** Extracts the items to dispatch from one trigger result. Receives the same context as the trigger's perform function. With `batchSize: 1` each item is delivered to its own execution; with `batchSize > 1` items are grouped into `TItem[]` slices. */
+    resolveItems?: (context: ActionContext<TConfigVars>, result: TriggerBaseResult<WithDiscoveryState<TPayload, TDiscoveryState>>) => TItem[];
+    /** Returns the cursor for the next page, or `null` to stop. A non-null return re-invokes the trigger with this object stamped onto `payload.discoveryState`. */
+    getNextDiscoveryState?: (context: ActionContext<TConfigVars>, result: TriggerBaseResult<WithDiscoveryState<TPayload, TDiscoveryState>>) => TDiscoveryState | null;
+}
+/**
+ * A trigger payload with its `discoveryState` field narrowed to `TDiscoveryState`,
+ * leaving every other field of `TPayload` intact. Lets a resolver type the cursor
+ * it reads back independently of how the base payload was parameterized.
+ */
+export type WithDiscoveryState<TPayload extends TriggerPayload, TDiscoveryState extends Record<string, unknown>> = Omit<TPayload, "discoveryState"> & {
+    discoveryState?: TDiscoveryState;
+};
+/**
+ * The single batch-dispatch config shared by a trigger's `triggerResolver` and
+ * `onDeployResolver` — they always batch the same way. One place for batch settings.
+ *
+ * On a CNI flow (`flow.batchConfig`) this value is authoritative. On a component trigger
+ * (`TriggerDefinition.batchConfig`) it's the default the platform seeds, which a low-code
+ * user may override per instance.
+ */
+export interface BatchConfig {
+    /** Number of items per batch. Must be an integer >= 1. `1` dispatches each item individually; `>1` groups items into batches. */
+    batchSize: number;
+    /** Max batches of a single execution dispatched concurrently. Must be an integer >= 1 when set. Omit for unlimited. */
+    concurrentBatchLimit?: number;
+}
 /**
  * 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 `TriggerResolverDecl` (the
+ * resolver support relationship) and `OnDeployDecl` (the on-deploy perform/resolver
+ * relationship), which enforce those constraints 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> & OnDeployDecl<TInputs, TConfigVars, TriggerPayload, TAllowsBranching, TResult>;
+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. */
     perform: TriggerPerformFunction<TInputs, TConfigVars, TAllowsBranching, TResult>;
+    /**
+     * Default batch-dispatch config shared by `triggerResolver` and `onDeployResolver`.
+     * Required when this trigger declares either (a `triggerResolver` with
+     * `triggerResolverSupport` `"valid"`/`"required"`, or an `onDeployResolver`).
+     */
+    batchConfig?: BatchConfig;
     /**
      * Function to execute when an instance of an integration with a flow that uses this trigger is deployed. See
      * https://prismatic.io/docs/custom-connectors/triggers/#instance-deploy-and-delete-events-for-triggers

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/dist/types/TriggerPerformFunction.d.ts

@@ -4,4 +4,4 @@ import type { ConfigVarResultCollection, Inputs } from "./Inputs";
 import type { TriggerPayload } from "./TriggerPayload";
 import type { TriggerResult } from "./TriggerResult";
 /** Definition of the function to perform when a Trigger is invoked. */
-export type TriggerPerformFunction<TInputs extends Inputs, TConfigVars extends ConfigVarResultCollection, TAllowsBranching extends boolean | undefined, TResult extends TriggerResult<TAllowsBranching, TriggerPayload>> = (context: ActionContext<TConfigVars>, payload: TriggerPayload, params: ActionInputParameters<TInputs>) => Promise<TResult>;
+export type TriggerPerformFunction<TInputs extends Inputs, TConfigVars extends ConfigVarResultCollection, TAllowsBranching extends boolean | undefined, TResult extends TriggerResult<TAllowsBranching, TriggerPayload>, TDiscoveryState extends Record<string, unknown> = Record<string, unknown>> = (context: ActionContext<TConfigVars>, payload: TriggerPayload<TDiscoveryState>, params: ActionInputParameters<TInputs>) => Promise<TResult>;

package/package.json

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