@prismatic-io/spectral 10.19.0 → 10.20.0

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, BatchTrigger, 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 { 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, TPaginationState extends Record<string, unknown> = Record<string, unknown>, T extends Flow<TInputs, TActionInputs, TPayload, TAllowsBranching, TResult, TTriggerPayload, TItem, TPaginationState> = Flow<TInputs, TActionInputs, TPayload, TAllowsBranching, TResult, TTriggerPayload, TItem, TPaginationState>>(definition: T & {
+    trigger?: BatchTrigger<TItem, TPaginationState>;
+}) => T;
+/**
+ * Builds a flow's batched `trigger` — the ergonomic way to define a batching flow. Instead of
+ * writing `onTrigger`/`onDeployTrigger` (returning a full payload) plus `triggerResolver`/
+ * `onDeployResolver` (to extract and paginate), each trigger fire returns `{ items,
+ * paginationState? }`: the records to dispatch and, when paginating, the cursor for the next
+ * page. spectral wraps the items into the wire payload and synthesizes the `resolveItems` and
+ * `getNextPaginationState` that read them back — there is no separate pagination callback.
+ *
+ * Supply the item and pagination-state types explicitly —
+ * `batchFlowTrigger<Order, { cursor: number }>({ ... })`. They flow through the whole flow:
+ * the trigger fires return `Order[]`, `payload.paginationState` 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 TPaginationState - the pagination state round-tripped via `payload.paginationState`.
+ * @see {@link https://prismatic.io/docs/integrations/code-native/flows/ | Code-Native Flows}
+ * @example
+ * import { flow, batchFlowTrigger } from "@prismatic-io/spectral";
+ *
+ * flow({
+ *   name: "Sync Orders",
+ *   stableKey: "sync-orders",
+ *   batchConfig: { batchSize: 50 },
+ *   trigger: batchFlowTrigger<Order, { cursor: number }>({
+ *     onTrigger: async (context, payload) => {
+ *       const page = await fetchOrders(payload.paginationState?.cursor);
+ *       return {
+ *         items: page.orders,
+ *         paginationState: page.nextCursor ? { cursor: page.nextCursor } : null,
+ *       };
+ *     },
+ *   }),
+ *   onExecution: async (context, params) => {
+ *     const orders = params.onTrigger.results.body.data; // Order | Order[]
+ *     return { data: orders };
+ *   },
+ * });
+ */
+export declare const batchFlowTrigger: <TItem, TPaginationState extends Record<string, unknown> = Record<string, unknown>>(trigger: BatchTrigger<TItem, TPaginationState>) => BatchTrigger<TItem, TPaginationState>;
 /**
  * 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.batchFlowTrigger = 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`/`TPaginationState` that the
+// `T extends Flow<...>` capture alone does not provide, while `T` still preserves the precise
+// literal type for the return value. They are inferred from a batched `trigger`'s
+// `items`/pagination-state types (see `batchFlowTrigger`).
+definition) => definition;
 exports.flow = flow;
+/**
+ * Builds a flow's batched `trigger` — the ergonomic way to define a batching flow. Instead of
+ * writing `onTrigger`/`onDeployTrigger` (returning a full payload) plus `triggerResolver`/
+ * `onDeployResolver` (to extract and paginate), each trigger fire returns `{ items,
+ * paginationState? }`: the records to dispatch and, when paginating, the cursor for the next
+ * page. spectral wraps the items into the wire payload and synthesizes the `resolveItems` and
+ * `getNextPaginationState` that read them back — there is no separate pagination callback.
+ *
+ * Supply the item and pagination-state types explicitly —
+ * `batchFlowTrigger<Order, { cursor: number }>({ ... })`. They flow through the whole flow:
+ * the trigger fires return `Order[]`, `payload.paginationState` 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 TPaginationState - the pagination state round-tripped via `payload.paginationState`.
+ * @see {@link https://prismatic.io/docs/integrations/code-native/flows/ | Code-Native Flows}
+ * @example
+ * import { flow, batchFlowTrigger } from "@prismatic-io/spectral";
+ *
+ * flow({
+ *   name: "Sync Orders",
+ *   stableKey: "sync-orders",
+ *   batchConfig: { batchSize: 50 },
+ *   trigger: batchFlowTrigger<Order, { cursor: number }>({
+ *     onTrigger: async (context, payload) => {
+ *       const page = await fetchOrders(payload.paginationState?.cursor);
+ *       return {
+ *         items: page.orders,
+ *         paginationState: page.nextCursor ? { cursor: page.nextCursor } : null,
+ *       };
+ *     },
+ *   }),
+ *   onExecution: async (context, params) => {
+ *     const orders = params.onTrigger.results.body.data; // Order | Order[]
+ *     return { data: orders };
+ *   },
+ * });
+ */
+const batchFlowTrigger = (trigger) => trigger;
+exports.batchFlowTrigger = batchFlowTrigger;
 /**
  * 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");
@@ -67,6 +67,89 @@ 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 {};
+    }
+    const { resolveItems, getNextPaginationState } = resolver;
+    return Object.assign(Object.assign({}, (resolveItems
+        ? {
+            resolveTriggerItems: resolveItems,
+            hasResolveTriggerItems: true,
+        }
+        : {})), (getNextPaginationState
+        ? {
+            getNextPaginationState,
+            hasGetNextDiscoveryState: true,
+        }
+        : {}));
+};
+const buildOnDeployResolverFields = (resolver) => {
+    if (!resolver) {
+        return {};
+    }
+    const { resolveItems, getNextPaginationState } = resolver;
+    return Object.assign(Object.assign({}, (resolveItems
+        ? {
+            resolveOnDeployItems: resolveItems,
+            hasResolveOnDeployItems: true,
+        }
+        : {})), (getNextPaginationState
+        ? {
+            getOnDeployNextPaginationState: getNextPaginationState,
+            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"]);
@@ -139,7 +222,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;
@@ -150,6 +240,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)) {
@@ -178,11 +288,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,
@@ -190,6 +300,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.d.ts

@@ -8,7 +8,7 @@ export declare const convertConfigPages: (pages: ConfigPages | undefined, userLe
 /** Converts typed QueueConfig to legacy format with usesFifoQueue and concurrencyLimit. */
 export declare const convertQueueConfig: (queueConfig: QueueConfig) => StandardQueueConfig;
 /** Converts a Flow into the structure necessary for YAML generation. */
-export declare const convertFlow: <TInputs extends Inputs, TActionInputs extends Inputs, TPayload extends TriggerPayload = TriggerPayload, TAllowsBranching extends boolean = boolean, TResult extends TriggerPerformResult<TAllowsBranching, TPayload> = TriggerPerformResult<TAllowsBranching, TPayload>>(flow: Flow<TInputs, TActionInputs, TPayload, TAllowsBranching, TResult>, componentRegistry: ComponentRegistry, referenceKey: string) => Record<string, unknown>;
+export declare const convertFlow: <TInputs extends Inputs, TActionInputs extends Inputs, TPayload extends TriggerPayload = TriggerPayload, TAllowsBranching extends boolean = boolean, TResult extends TriggerPerformResult<TAllowsBranching, TPayload> = TriggerPerformResult<TAllowsBranching, TPayload>>(rawFlow: Flow<TInputs, TActionInputs, TPayload, TAllowsBranching, TResult>, componentRegistry: ComponentRegistry, referenceKey: string) => Record<string, unknown>;
 /** Converts an input value to the expected server type by its collection type. */
 export declare const convertInputValue: (value: unknown, collectionType: CollectionType | undefined) => unknown;
 /** Converts a Config Var into the structure necessary for YAML generation. */

package/dist/serverTypes/convertIntegration.js

@@ -8,6 +8,17 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
         step((generator = generator.apply(thisArg, _arguments || [])).next());
     });
 };
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
@@ -29,6 +40,59 @@ const integration_1 = require("./integration");
 const perform_1 = require("./perform");
 exports.CONCURRENCY_LIMIT_MAX = 15;
 exports.CONCURRENCY_LIMIT_MIN = 2;
+/**
+ * Default `resolveItems`: a batched `trigger`'s fires return their records under
+ * `payload.body.data` (the wrapper {@link normalizeBatchedFlow} builds writes them there),
+ * so extraction is just reading that array back. Authors never write this themselves.
+ */
+const defaultResolveItems = (_context, result) => result.payload.body.data;
+/**
+ * Default `getNextPaginationState`: a batched fire returns the next page's cursor as
+ * `paginationState`, which the wrapper {@link normalizeBatchedFlow} builds stamps onto
+ * `payload.paginationState`. Reading it back (defaulting to `null`) is the whole loop: a
+ * non-null value re-invokes the fire, `null` ends it. Authors never write this.
+ */
+const defaultGetNextPaginationState = (_context, result) => { var _a; return (_a = result.payload.paginationState) !== null && _a !== void 0 ? _a : null; };
+/**
+ * Expands a flow's batched `trigger` (built with `batchFlowTrigger`) into the flat
+ * `onTrigger`/`onDeployTrigger`/`triggerResolver`/`onDeployResolver` shape the rest of the
+ * conversion pipeline already understands. The trigger fires return `{ items, paginationState? }`;
+ * here we wrap each into a `TriggerPerformFunction` that emits `{ payload: { …payload, body: {
+ * data: items }, paginationState } }`, then synthesize the default `resolveItems` (reads the
+ * items back) and `getNextPaginationState` (reads the cursor back). Flows without a `trigger`
+ * pass through unchanged.
+ *
+ * Returns the same `Flow` type it received; the synthesized `triggerResolver`/`onDeployResolver`
+ * are wire-only fields (not on the author-facing `Flow`), read downstream via `"x" in flow` checks.
+ */
+const normalizeBatchedFlow = (flow) => {
+    const trigger = "trigger" in flow ? flow.trigger : undefined;
+    if (!trigger) {
+        return flow;
+    }
+    const { onTrigger, onDeploy } = trigger;
+    // Wrap a batched fire (returns `{ items, paginationState?, response? }`) into a
+    // TriggerPerformFunction that emits the wire payload shape: items at `body.data` and the
+    // next-page cursor at `paginationState` (defaulting `null` to terminate the loop). The
+    // incoming payload's `paginationState` was already consumed by the fire, so overwriting it
+    // with the returned cursor is safe — `getNextPaginationState` reads it straight back.
+    const wrapFire = (fire) => (context, payload) => __awaiter(void 0, void 0, void 0, function* () {
+        const { items, paginationState, response } = yield fire(context, payload);
+        return Object.assign({ payload: Object.assign(Object.assign({}, payload), { body: { data: items, contentType: "application/json" }, paginationState: paginationState !== null && paginationState !== void 0 ? paginationState : null }) }, (response ? { response } : {}));
+    });
+    const _a = flow, { trigger: _omitTrigger } = _a, rest = __rest(_a, ["trigger"]);
+    return Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({}, rest), { onTrigger: wrapFire(onTrigger) }), (onDeploy ? { onDeployTrigger: wrapFire(onDeploy) } : {})), { triggerResolver: {
+            resolveItems: defaultResolveItems,
+            getNextPaginationState: defaultGetNextPaginationState,
+        } }), (onDeploy
+        ? {
+            onDeployResolver: {
+                resolveItems: defaultResolveItems,
+                getNextPaginationState: defaultGetNextPaginationState,
+            },
+        }
+        : {}));
+};
 const convertIntegration = (definition) => {
     var _a, _b, _c;
     // Generate a unique reference key that will be used to reference the
@@ -94,7 +158,11 @@ const convertConfigPages = (pages, userLevelConfigured) => {
         }) })));
 };
 exports.convertConfigPages = convertConfigPages;
-const codeNativeIntegrationYaml = ({ name, description, category, documentation, version, labels, endpointType, triggerPreprocessFlowConfig, flows, configPages, userLevelConfigPages, scopedConfigVars, instanceProfile, componentRegistry = {}, }, referenceKey, configVars, metadata) => {
+const codeNativeIntegrationYaml = ({ name, description, category, documentation, version, labels, endpointType, triggerPreprocessFlowConfig, flows: rawFlows, configPages, userLevelConfigPages, scopedConfigVars, instanceProfile, componentRegistry = {}, }, referenceKey, configVars, metadata) => {
+    // Expand any batched `trigger` (built with `batchFlowTrigger`) into the flat
+    // onTrigger/onDeployTrigger/triggerResolver/onDeployResolver shape the rest of this
+    // pipeline (convertFlow + the trigger reducer) already handles.
+    const flows = rawFlows.map((flow) => normalizeBatchedFlow(flow));
     // Find the preprocess flow config on the flow, if one exists.
     const preprocessFlows = flows.filter((flow) => flow.preprocessFlowConfig);
     // Do some validation of preprocess flow configs.
@@ -310,8 +378,11 @@ const convertFlowSchemas = (flowKey, schemas) => {
     }, {});
 };
 /** Converts a Flow into the structure necessary for YAML generation. */
-const convertFlow = (flow, componentRegistry, referenceKey) => {
+const convertFlow = (rawFlow, componentRegistry, referenceKey) => {
     var _a;
+    // Expand a batched `trigger` into the flat shape this function serializes. Idempotent: a flow
+    // that already lacks `trigger` (including one pre-normalized by `convertIntegration`) is returned as-is.
+    const flow = normalizeBatchedFlow(rawFlow);
     const result = Object.assign({}, flow);
     result.onTrigger = undefined;
     result.trigger = undefined;
@@ -319,6 +390,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;
@@ -412,6 +484,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/getNextPaginationState) 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"),
@@ -695,7 +791,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)}`);
     }
@@ -751,7 +851,9 @@ const convertOnExecution = (onExecution, componentRegistry) => (context, params)
 });
 /** Creates the structure necessary to import a Component as part of a
  *  Code Native integration. */
-const codeNativeIntegrationComponent = ({ name, iconPath, description, flows = [], componentRegistry = {}, }, referenceKey, configVars) => {
+const codeNativeIntegrationComponent = ({ name, iconPath, description, flows: rawFlows = [], componentRegistry = {}, }, referenceKey, configVars) => {
+    // Expand any batched `trigger` so the action/trigger reducers below see the flat shape.
+    const flows = rawFlows.map((flow) => normalizeBatchedFlow(flow));
     const convertedActions = flows.reduce((result, { name, onExecution }) => {
         const key = flowFunctionKey(name, "onExecution");
         return Object.assign(Object.assign({}, result), { [key]: {
@@ -764,7 +866,12 @@ const codeNativeIntegrationComponent = ({ name, iconPath, description, flows = [
                 inputs: [],
             } });
     }, {});
-    const convertedTriggers = flows.reduce((result, { name, onTrigger, onInstanceDeploy, onInstanceDelete, webhookLifecycleHandlers, schedule, triggerType, }) => {
+    const convertedTriggers = flows.reduce((result, flow) => {
+        var _a;
+        const { name, onTrigger, onInstanceDeploy, onInstanceDelete, webhookLifecycleHandlers, schedule, triggerType, onDeployTrigger, } = flow;
+        // `batchConfig`/`triggerResolver`/`onDeployResolver` are wire-only fields synthesized by
+        // `normalizeBatchedFlow`; they aren't on the author-facing `Flow` type, so read via cast.
+        const { batchConfig, triggerResolver, onDeployResolver } = flow;
         if (!flowUsesWrapperTrigger({
             onTrigger,
             onInstanceDelete,
@@ -799,26 +906,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: wrapperTriggerInputsFromReference(onTrigger, componentRegistry),
-                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: wrapperTriggerInputsFromReference(onTrigger, componentRegistry), 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.getNextPaginationState
+                    ? {
+                        getNextPaginationState: triggerResolver.getNextPaginationState,
+                        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.getNextPaginationState
+                    ? {
+                        getOnDeployNextPaginationState: onDeployResolver.getNextPaginationState,
+                        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, getNextPaginationState, ...) 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;
+    getNextPaginationState?: (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;
+    getOnDeployNextPaginationState?: (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/TPaginationState/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

@@ -4,9 +4,11 @@ import type { ComponentRegistry, ConfigVarExpression, TriggerReference, ValueExp
 import type { ConfigPages, UserLevelConfigPages } from "./ConfigPages";
 import type { ConfigVars } from "./ConfigVars";
 import type { FlowDefinitionFlowSchema } from "./FlowSchemas";
+import type { HttpResponse } from "./HttpResponse";
 import type { Inputs } from "./Inputs";
 import type { PollingTriggerPerformFunction } from "./PollingTriggerDefinition";
 import type { ScopedConfigVarMap } from "./ScopedConfigVars";
+import type { BatchConfig } from "./TriggerDefinition";
 import type { TriggerEventFunction } from "./TriggerEventFunction";
 import type { TriggerPayload } from "./TriggerPayload";
 import type { TriggerPerformFunction } from "./TriggerPerformFunction";
@@ -46,8 +48,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`/`TPaginationState`/`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 +77,64 @@ 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;
+    };
+};
+/**
+ * The page of records a batched trigger fire (`onTrigger`/`onDeploy`) returns. The author
+ * returns the items plus, when paginating, the cursor for the next page. spectral wraps the
+ * items into the wire trigger payload (`body.data`), carries the `paginationState` to the next
+ * round, and synthesizes the resolver that reads both back. There is no separate pagination
+ * callback to define.
+ */
+export interface BatchedTriggerReturn<TItem, TPaginationState extends Record<string, unknown> = Record<string, unknown>> {
+    /** The records produced by this trigger fire. Chunked into batches of the flow's `batchConfig.batchSize`. */
+    items: TItem[];
+    /**
+     * Cursor for the next page. Return it to paginate — the fire is re-invoked with this object on
+     * `payload.paginationState`. Omit or return `null` to stop. Compute it here from the fetch
+     * response, where the next-page token is still in scope.
+     */
+    paginationState?: TPaginationState | null;
+    /** Optional HTTP response to the request that invoked the integration. */
+    response?: HttpResponse;
+}
+/**
+ * A batched trigger built by {@link batchFlowTrigger}. Bundles the normal and on-deploy trigger
+ * fires, each returning `{ items, paginationState? }`. The two type parameters — supplied
+ * explicitly to `batchFlowTrigger<TItem, TPaginationState>(...)` — flow through to the rest of
+ * the flow: `TItem` types `onExecution`'s `params.onTrigger.results.body.data`, and
+ * `TPaginationState` types both `payload.paginationState` (read on the way in) and the
+ * `paginationState` each fire returns (the next page's cursor).
+ */
+export interface BatchTrigger<TItem, TPaginationState extends Record<string, unknown> = Record<string, unknown>> {
+    /**
+     * The trigger function for this flow. Fetches a page of records and returns them as `items`,
+     * plus the next page's `paginationState` to paginate (omit/`null` to stop). Read the cursor for
+     * the current page from `payload.paginationState`.
+     */
+    onTrigger: (context: ActionContext<ConfigVars>, payload: TriggerPayload<TPaginationState>) => Promise<BatchedTriggerReturn<TItem, TPaginationState>>;
+    /**
+     * The on-deploy trigger fire, run once on initial instance deploy. Same shape as `onTrigger`;
+     * return `paginationState` to paginate the backfill.
+     */
+    onDeploy?: (context: ActionContext<ConfigVars>, payload: TriggerPayload<TPaginationState>) => Promise<BatchedTriggerReturn<TItem, TPaginationState>>;
+}
+export type FlowOnExecution<TTriggerPayload extends TriggerPayload, TItem = unknown> = ActionPerformFunction<{
     onTrigger: {
         type: "data";
         label: string;
         clean: (value: unknown) => {
-            results: TTriggerPayload;
+            results: BatchedTriggerPayload<TTriggerPayload, TItem>;
         };
     };
 }, ConfigVars, {
@@ -85,8 +144,56 @@ export type FlowExecutionContext = ActionContext<ConfigVars, {
     [Key in keyof ComponentRegistry]: ComponentRegistry[Key]["actions"];
 }>;
 export type FlowExecutionContextActions = FlowExecutionContext["components"];
+/**
+ * The batch-discriminated fields of a flow. A flow either batches or it does not, and
+ * the presence of `batchConfig` is the discriminant TypeScript uses to choose a member:
+ *
+ * - {@link BatchFields}: `batchConfig` is present, which requires a batched `trigger`
+ *   (built with {@link batchFlowTrigger}). The flat `onTrigger`/`onDeployTrigger` are
+ *   forbidden — the trigger fires live inside the `trigger` object.
+ * - {@link NonBatchFields}: `batchConfig`/`trigger` are absent; the flow uses the plain
+ *   `onTrigger`/`onDeployTrigger` on its variant.
+ *
+ * Discrimination is structural — it depends only on whether the object literal you write
+ * has a `batchConfig` key — so it works without TypeScript having to infer any type
+ * parameter from the value. The batched-vs-not shape of `onExecution`'s payload is handled
+ * separately, on `FlowBase`, via `TItem`: when a `trigger` is present `TItem` is inferred
+ * (so `onExecution` sees `TItem | TItem[]`); otherwise it stays `unknown` and the payload
+ * is left untouched (see {@link BatchedTriggerPayload}). Keeping `onExecution` out of this
+ * union is deliberate — a function property living in a union member loses contextual
+ * parameter typing, which would make `onExecution`'s `context`/`params` implicitly `any`.
+ */
+interface BatchFields<TItem, TPaginationState extends Record<string, unknown>> {
+    /**
+     * Batch-dispatch config for this flow. Items returned by the `trigger`'s fires are chunked
+     * into batches of `batchSize`. For a CNI flow this value is authoritative (what's written
+     * here is what's used). Its presence requires a batched `trigger`.
+     */
+    batchConfig: BatchConfig;
+    /**
+     * The batched trigger for this flow, built with {@link batchFlowTrigger}. Its fires
+     * (`onTrigger`/`onDeploy`) return just `items`; spectral synthesizes the resolver that
+     * extracts them and maps the pagination callbacks. Required when `batchConfig` is set.
+     */
+    trigger: BatchTrigger<TItem, TPaginationState>;
+    /** A batched flow's trigger fires live inside `trigger`; the flat `onTrigger` is forbidden. */
+    onTrigger?: never;
+    /** A batched flow's on-deploy fire lives inside `trigger`; the flat `onDeployTrigger` is forbidden. */
+    onDeployTrigger?: never;
+}
+interface NonBatchFields {
+    /** A non-batching flow may not declare batch config. */
+    batchConfig?: never;
+    /** A non-batching flow may not declare a batched trigger. */
+    trigger?: never;
+}
+/**
+ * The discriminated union coupling `batchConfig` and the batched `trigger`. Intersected
+ * into each flow variant at {@link Flow}.
+ */
+type BatchDiscriminant<TItem, TPaginationState extends Record<string, unknown>> = BatchFields<TItem, TPaginationState> | NonBatchFields;
 /** Base properties shared by all flow types. */
-interface FlowBase<TTriggerPayload extends TriggerPayload = TriggerPayload> {
+interface FlowBase<TTriggerPayload extends TriggerPayload = TriggerPayload, TItem = 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. */
@@ -143,23 +250,33 @@ interface FlowBase<TTriggerPayload extends TriggerPayload = TriggerPayload> {
         /** Function to execute for webhook teardown. */
         delete: TriggerEventFunction<Inputs, ConfigVars>;
     };
-    /** Specifies the main function for this flow which is run when this flow is invoked. */
-    onExecution: FlowOnExecution<TTriggerPayload>;
+    /**
+     * Specifies the main function for this flow which is run when this flow is invoked.
+     * When the flow batches (has a `triggerResolver`/`onDeployResolver`, so `TItem` is
+     * inferred), `params.onTrigger.results.body.data` is typed as the resolved item type
+     * (`TItem | TItem[]`); otherwise the trigger payload is left untouched.
+     */
+    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, TPaginationState extends Record<string, unknown> = Record<string, unknown>> extends FlowBase<TTriggerPayload, TItem> {
     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, TPaginationState>;
+    /**
+     * 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.
+     */
+    onDeployTrigger?: TriggerPerformFunction<TInputs, ConfigVars, TAllowsBranching, TResult, TPaginationState>;
 }
 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, TPaginationState extends Record<string, unknown> = Record<string, unknown>> extends FlowBase<TTriggerPayload, TItem> {
     /**
      * 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 +290,14 @@ 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.
+     */
+    onDeployTrigger?: TriggerPerformFunction<TInputs, ConfigVars, TAllowsBranching, TResult, TPaginationState>;
 }
 /** 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, TPaginationState extends Record<string, unknown> = Record<string, unknown>> = (StandardFlow<TInputs, TPayload, TAllowsBranching, TResult, TTriggerPayload, TItem, TPaginationState> & BatchDiscriminant<TItem, TPaginationState>) | (PollingFlow<TInputs, TActionInputs, TPayload, TAllowsBranching, TResult, TTriggerPayload, TItem, TPaginationState> & BatchDiscriminant<TItem, TPaginationState>);
 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, TPaginationState extends Record<string, unknown> = Record<string, unknown>> = {
+    triggerResolverSupport?: "invalid" | undefined;
+    triggerResolver?: undefined;
+} | {
+    triggerResolverSupport: "valid";
+    triggerResolver?: TriggerResolverBehavior<TConfigVars, TPayload, TItem, TPaginationState>;
+} | {
+    triggerResolverSupport: "required";
+    triggerResolver: TriggerResolverBehavior<TConfigVars, TPayload, TItem, TPaginationState>;
+};
+/**
+ * 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, TPaginationState extends Record<string, unknown> = Record<string, unknown>> = {
+    onDeployPerform?: undefined;
+    onDeployResolver?: undefined;
+} | {
+    onDeployPerform: TriggerPerformFunction<TInputs, TConfigVars, TAllowsBranching, TResult>;
+    onDeployResolver?: TriggerResolverBehavior<TConfigVars, TPayload, TItem, TPaginationState>;
+};
 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
+ *                    │
+ *                    └─ getNextPaginationState ──▶ payload.paginationState ──▶ 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 TPaginationState - the pagination cursor. Whatever
+ *   `getNextPaginationState` returns is what the next round reads back on
+ *   `payload.paginationState` (see {@link TriggerPayload}). The `result.payload`
+ *   passed to both callbacks has its `paginationState` 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, TPaginationState 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<WithPaginationState<TPayload, TPaginationState>>) => 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.paginationState`. */
+    getNextPaginationState?: (context: ActionContext<TConfigVars>, result: TriggerBaseResult<WithPaginationState<TPayload, TPaginationState>>) => TPaginationState | null;
+}
+/**
+ * A trigger payload with its `paginationState` field narrowed to `TPaginationState`,
+ * 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 WithPaginationState<TPayload extends TriggerPayload, TPaginationState extends Record<string, unknown>> = Omit<TPayload, "paginationState"> & {
+    paginationState?: TPaginationState;
+};
+/**
+ * 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 `TPaginationState` parameter types the `paginationState` field, so authors who
+ * declare a pagination-state shape on their `getNextPaginationState` resolver can read back
+ * the same shape on the next round's payload. Defaults to `Record<string, unknown>`.
+ */
+export interface TriggerPayload<TPaginationState 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 `getNextPaginationState` from the previous round.
+     *  Absent on the initial invocation. */
+    paginationState?: TPaginationState;
 }

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>, TPaginationState extends Record<string, unknown> = Record<string, unknown>> = (context: ActionContext<TConfigVars>, payload: TriggerPayload<TPaginationState>, params: ActionInputParameters<TInputs>) => Promise<TResult>;

package/package.json

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