@prismatic-io/spectral 10.18.9-preview.1 → 10.19.1-preview.0

package/dist/generators/componentManifest/getInputs.js

@@ -73,7 +73,7 @@ exports.INPUT_TYPE_MAP = {
 const getInputValueType = (input) => {
     var _a, _b;
     if (input.type === "structuredObject") {
-        return structuredObjectTypeString((_a = input.inputs) !== null && _a !== void 0 ? _a : []);
+        return wrapCollection(structuredObjectTypeString((_a = input.inputs) !== null && _a !== void 0 ? _a : []), input.collection);
     }
     if (input.type === "dynamicObject") {
         return dynamicObjectTypeString((_b = input.inputs) !== null && _b !== void 0 ? _b : []);
@@ -138,7 +138,7 @@ const getLeafBaseType = (child) => {
 const getLeafTypeString = (child) => {
     var _a;
     if (child.type === "structuredObject") {
-        return structuredObjectTypeString((_a = child.inputs) !== null && _a !== void 0 ? _a : []);
+        return wrapCollection(structuredObjectTypeString((_a = child.inputs) !== null && _a !== void 0 ? _a : []), child.collection);
     }
     return wrapCollection(getLeafBaseType(child), child.collection);
 };

package/dist/index.d.ts

@@ -73,23 +73,24 @@ 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, 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 & {
-    trigger?: BatchTrigger<TItem, TDiscoveryState>;
+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), the trigger fires return just their `items` and
- * the pagination callbacks live alongside them. spectral wraps the items into the wire payload
- * and synthesizes the `resolveItems` that reads them back.
+ * `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.discoveryState` reads back as `{ cursor: number }`,
+ * 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.discoveryState`.
+ * @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";
@@ -100,12 +101,11 @@ export declare const flow: <TInputs extends Inputs, TActionInputs extends Inputs
  *   batchConfig: { batchSize: 50 },
  *   trigger: batchFlowTrigger<Order, { cursor: number }>({
  *     onTrigger: async (context, payload) => {
- *       const page = await fetchOrders(payload.discoveryState?.cursor);
- *       return { items: page.orders };
- *     },
- *     getNextOnTriggerPaginationState: (context, result) => {
- *       const next = result.payload.discoveryState?.cursor;
- *       return next === undefined ? null : { cursor: next };
+ *       const page = await fetchOrders(payload.paginationState?.cursor);
+ *       return {
+ *         items: page.orders,
+ *         paginationState: page.nextCursor ? { cursor: page.nextCursor } : null,
+ *       };
  *     },
  *   }),
  *   onExecution: async (context, params) => {

package/dist/index.js

@@ -103,7 +103,7 @@ exports.integration = integration;
  * });
  */
 const flow = (
-// The intersection adds an explicit inference site for `TItem`/`TDiscoveryState` that the
+// 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`).
@@ -112,17 +112,18 @@ 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), the trigger fires return just their `items` and
- * the pagination callbacks live alongside them. spectral wraps the items into the wire payload
- * and synthesizes the `resolveItems` that reads them back.
+ * `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.discoveryState` reads back as `{ cursor: number }`,
+ * 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.discoveryState`.
+ * @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";
@@ -133,12 +134,11 @@ exports.flow = flow;
  *   batchConfig: { batchSize: 50 },
  *   trigger: batchFlowTrigger<Order, { cursor: number }>({
  *     onTrigger: async (context, payload) => {
- *       const page = await fetchOrders(payload.discoveryState?.cursor);
- *       return { items: page.orders };
- *     },
- *     getNextOnTriggerPaginationState: (context, result) => {
- *       const next = result.payload.discoveryState?.cursor;
- *       return next === undefined ? null : { cursor: next };
+ *       const page = await fetchOrders(payload.paginationState?.cursor);
+ *       return {
+ *         items: page.orders,
+ *         paginationState: page.nextCursor ? { cursor: page.nextCursor } : null,
+ *       };
  *     },
  *   }),
  *   onExecution: async (context, params) => {

package/dist/serverTypes/convertComponent.js

@@ -27,12 +27,19 @@ const isPlainObject = (value) => value !== null && typeof value === "object" &&
 const cleanerFor = (input) => {
     if (input.type === "structuredObject") {
         const childCleaners = Object.entries(input.inputs).reduce((acc, [childKey, childDef]) => (Object.assign(Object.assign({}, acc), { [childKey]: (0, exports.cleanerFor)(childDef) })), {});
-        return (value) => {
-            if (!isPlainObject(value)) {
-                return value;
-            }
-            return (0, perform_1.cleanParams)(value, childCleaners);
-        };
+        const cleanRecord = (value) => isPlainObject(value) ? (0, perform_1.cleanParams)(value, childCleaners) : value;
+        if (input.collection === "valuelist") {
+            return (value) => (Array.isArray(value) ? value.map(cleanRecord) : value);
+        }
+        if (input.collection === "keyvaluelist") {
+            // Entries arrive as KeyValuePair envelopes; the object to clean
+            // lives under `value`.
+            return (value) => Array.isArray(value)
+                ? value.map((entry) => isPlainObject(entry) && "value" in entry
+                    ? Object.assign(Object.assign({}, entry), { value: cleanRecord(entry.value) }) : entry)
+                : value;
+        }
+        return cleanRecord;
     }
     if (input.type === "dynamicObject") {
         const configCleaners = {};
@@ -113,14 +120,15 @@ const buildTriggerResolverFields = (resolver) => {
     if (!resolver) {
         return {};
     }
-    return Object.assign(Object.assign({}, (resolver.resolveItems
+    const { resolveItems, getNextPaginationState } = resolver;
+    return Object.assign(Object.assign({}, (resolveItems
         ? {
-            resolveTriggerItems: resolver.resolveItems,
+            resolveTriggerItems: resolveItems,
             hasResolveTriggerItems: true,
         }
-        : {})), (resolver.getNextDiscoveryState
+        : {})), (getNextPaginationState
         ? {
-            getNextDiscoveryState: resolver.getNextDiscoveryState,
+            getNextPaginationState,
             hasGetNextDiscoveryState: true,
         }
         : {}));
@@ -129,14 +137,15 @@ const buildOnDeployResolverFields = (resolver) => {
     if (!resolver) {
         return {};
     }
-    return Object.assign(Object.assign({}, (resolver.resolveItems
+    const { resolveItems, getNextPaginationState } = resolver;
+    return Object.assign(Object.assign({}, (resolveItems
         ? {
-            resolveOnDeployItems: resolver.resolveItems,
+            resolveOnDeployItems: resolveItems,
             hasResolveOnDeployItems: true,
         }
-        : {})), (resolver.getNextDiscoveryState
+        : {})), (getNextPaginationState
         ? {
-            getOnDeployNextDiscoveryState: resolver.getNextDiscoveryState,
+            getOnDeployNextPaginationState: getNextPaginationState,
             hasGetOnDeployNextDiscoveryState: true,
         }
         : {}));

package/dist/serverTypes/convertIntegration.js

@@ -46,13 +46,21 @@ exports.CONCURRENCY_LIMIT_MIN = 2;
  * 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 just `{ items }`; here we
- * wrap each into a `TriggerPerformFunction` that emits `{ payload: { …payload, body: { data:
- * items } } }`, synthesize the default `resolveItems`, and map the pagination callbacks onto
- * the resolver `getNextDiscoveryState`. Flows without a `trigger` pass through unchanged.
+ * 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.
@@ -62,21 +70,26 @@ const normalizeBatchedFlow = (flow) => {
     if (!trigger) {
         return flow;
     }
-    const { onTrigger, onDeploy, getNextOnTriggerPaginationState, getNextOnDeployPaginationState } = trigger;
-    // Wrap a batched fire (returns `{ items, response? }`) into a TriggerPerformFunction that
-    // emits the wire payload shape (`body.data = items`), preserving the incoming payload fields.
+    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, response } = yield fire(context, payload);
-        return Object.assign({ payload: Object.assign(Object.assign({}, payload), { body: { data: items, contentType: "application/json" } }) }, (response ? { response } : {}));
+        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: Object.assign({ resolveItems: defaultResolveItems }, (getNextOnTriggerPaginationState
-            ? { getNextDiscoveryState: getNextOnTriggerPaginationState }
-            : {})) }), (onDeploy
+    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: Object.assign({ resolveItems: defaultResolveItems }, (getNextOnDeployPaginationState
-                ? { getNextDiscoveryState: getNextOnDeployPaginationState }
-                : {})),
+            onDeployResolver: {
+                resolveItems: defaultResolveItems,
+                getNextPaginationState: defaultGetNextPaginationState,
+            },
         }
         : {}));
 };
@@ -474,7 +487,7 @@ const convertFlow = (rawFlow, 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
+    // 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
@@ -907,9 +920,9 @@ const codeNativeIntegrationComponent = ({ name, iconPath, description, flows: ra
                         resolveTriggerItems: triggerResolver.resolveItems,
                         hasResolveTriggerItems: true,
                     }
-                    : {})), (triggerResolver.getNextDiscoveryState
+                    : {})), (triggerResolver.getNextPaginationState
                     ? {
-                        getNextDiscoveryState: triggerResolver.getNextDiscoveryState,
+                        getNextPaginationState: triggerResolver.getNextPaginationState,
                         hasGetNextDiscoveryState: true,
                     }
                     : {})) : {})), (onDeployTrigger
@@ -926,9 +939,9 @@ const codeNativeIntegrationComponent = ({ name, iconPath, description, flows: ra
                         resolveOnDeployItems: onDeployResolver.resolveItems,
                         hasResolveOnDeployItems: true,
                     }
-                    : {})), (onDeployResolver.getNextDiscoveryState
+                    : {})), (onDeployResolver.getNextPaginationState
                     ? {
-                        getOnDeployNextDiscoveryState: onDeployResolver.getNextDiscoveryState,
+                        getOnDeployNextPaginationState: onDeployResolver.getNextPaginationState,
                         hasGetOnDeployNextDiscoveryState: true,
                     }
                     : {})) : {})) });

package/dist/serverTypes/index.d.ts

@@ -130,7 +130,7 @@ 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
+ * (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.
  *
@@ -175,13 +175,13 @@ export interface Trigger<TInputs extends Inputs, TActionInputs extends Inputs, T
     triggerResolverDefaultConcurrentBatchLimit?: number;
     resolveTriggerItems?: (context: ActionContext<TConfigVars>, result: TriggerBaseResult<TPayload>) => unknown[];
     hasResolveTriggerItems?: boolean;
-    getNextDiscoveryState?: (context: ActionContext<TConfigVars>, result: TriggerBaseResult<TPayload>) => Record<string, unknown> | null;
+    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;
-    getOnDeployNextDiscoveryState?: (context: ActionContext<TConfigVars>, result: TriggerBaseResult<TPayload>) => Record<string, unknown> | null;
+    getOnDeployNextPaginationState?: (context: ActionContext<TConfigVars>, result: TriggerBaseResult<TPayload>) => Record<string, unknown> | null;
     hasGetOnDeployNextDiscoveryState?: boolean;
     examplePayload?: unknown;
     isCommonTrigger?: boolean;

package/dist/testing.js

@@ -409,7 +409,7 @@ const createConfigVars = (values) => {
  * });
  */
 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
+// `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, } = {}) {

package/dist/types/ActionInputParameters.d.ts

@@ -1,15 +1,17 @@
 import type { ConditionalExpression } from "./conditional-logic";
 import type { Connection, DynamicObjectInputField, InputCleanFunction, InputFieldCollection, Inputs, KeyValuePair, StructuredObjectInputField } from "./Inputs";
 /** Resolves a single InputFieldDefinition's runtime value type.
- * - structuredObject: record of declared children's resolved value types.
+ * - structuredObject: record of declared children's resolved value types;
+ *   with `collection` set, a list (`valuelist`) or `KeyValuePair` list
+ *   (`keyvaluelist`) of that record.
  * - dynamicObject: discriminated union keyed by the selected configuration,
  *   with the configuration's resolved inputs nested under `values` to avoid
  *   collisions with the `configuration` discriminant key.
  * The depth caps (`LeafInputFieldDefinition`, `StructuredOrLeafInputFieldDefinition`)
  * prevent unbounded recursion. */
-type InputValue<T> = T extends StructuredObjectInputField ? {
+type InputValue<T> = T extends StructuredObjectInputField ? ExtractValue<{
     [K in keyof T["inputs"]]: InputValue<T["inputs"][K]>;
-} : T extends DynamicObjectInputField ? {
+}, T["collection"]> : T extends DynamicObjectInputField ? {
     [C in keyof T["configurations"]]: {
         configuration: C;
         values: {

package/dist/types/Inputs.d.ts

@@ -307,6 +307,10 @@ export type StructuredOrLeafInputFieldDefinition = LeafInputFieldDefinition | St
 export type StructuredObjectInputField = Omit<BaseInputField, "dataSource" | "example" | "placeholder" | "required"> & {
     /** Data type the input will collect. */
     type: "structuredObject";
+    /** Collection type of the input; when set, the input collects a list
+     * (`valuelist`) or keyed list (`keyvaluelist`) of objects instead of a
+     * single object. */
+    collection?: InputFieldCollection;
     /** Nested input fields keyed by their local key. */
     inputs: Record<string, LeafInputFieldDefinition>;
 };

package/dist/types/IntegrationDefinition.d.ts

@@ -8,11 +8,11 @@ import type { HttpResponse } from "./HttpResponse";
 import type { Inputs } from "./Inputs";
 import type { PollingTriggerPerformFunction } from "./PollingTriggerDefinition";
 import type { ScopedConfigVarMap } from "./ScopedConfigVars";
-import type { BatchConfig, WithDiscoveryState } from "./TriggerDefinition";
+import type { BatchConfig } from "./TriggerDefinition";
 import type { TriggerEventFunction } from "./TriggerEventFunction";
 import type { TriggerPayload } from "./TriggerPayload";
 import type { TriggerPerformFunction } from "./TriggerPerformFunction";
-import type { TriggerBaseResult, TriggerResult } from "./TriggerResult";
+import type { TriggerResult } from "./TriggerResult";
 /**
  * Defines attributes of a code-native integration. See
  * https://prismatic.io/docs/integrations/code-native/
@@ -49,7 +49,7 @@ 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
+     * 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.
@@ -91,45 +91,43 @@ export type BatchedTriggerPayload<TPayload extends TriggerPayload, TItem> = unkn
 };
 /**
  * The page of records a batched trigger fire (`onTrigger`/`onDeploy`) returns. The author
- * returns just the items; spectral wraps them into the wire trigger payload (`body.data`)
- * and synthesizes the resolver that extracts them. Returning `items` is the whole contract —
- * there is no `payload` to thread by hand.
+ * 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> {
+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;
 }
-/**
- * The pagination callback for a batched trigger fire. Returns the state for the next page,
- * or `null` to stop. A non-null return re-invokes the corresponding trigger with this object
- * stamped onto `payload.discoveryState`; the loop ends when it returns `null`.
- */
-export type BatchPaginationStateFunction<TPaginationState extends Record<string, unknown>> = (context: ActionContext<ConfigVars>, result: TriggerBaseResult<WithDiscoveryState<TriggerPayload, TPaginationState>>) => TPaginationState | null;
 /**
  * A batched trigger built by {@link batchFlowTrigger}. Bundles the normal and on-deploy trigger
- * fires (each returning just `items`) with their pagination callbacks. The two type parameters
- * — supplied explicitly to `batchTrigger<TItem, TPaginationState>(...)` — flow through to the
- * rest of the flow: `TItem` types `onExecution`'s `params.onTrigger.results.body.data`, and
- * `TPaginationState` types `payload.discoveryState` and the pagination callbacks' return.
+ * 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`.
-     * Re-invoked once per pagination round (see `getNextOnTriggerPaginationState`); read the
-     * cursor for the current page from `payload.discoveryState`.
+     * 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>>;
+    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`;
-     * pair with `getNextOnDeployPaginationState` to paginate.
+     * return `paginationState` to paginate the backfill.
      */
-    onDeploy?: (context: ActionContext<ConfigVars>, payload: TriggerPayload<TPaginationState>) => Promise<BatchedTriggerReturn<TItem>>;
-    /** Pagination for `onTrigger`: return the next page's state, or `null` to stop. */
-    getNextOnTriggerPaginationState?: BatchPaginationStateFunction<TPaginationState>;
-    /** Pagination for `onDeploy`: return the next page's state, or `null` to stop. */
-    getNextOnDeployPaginationState?: BatchPaginationStateFunction<TPaginationState>;
+    onDeploy?: (context: ActionContext<ConfigVars>, payload: TriggerPayload<TPaginationState>) => Promise<BatchedTriggerReturn<TItem, TPaginationState>>;
 }
 export type FlowOnExecution<TTriggerPayload extends TriggerPayload, TItem = unknown> = ActionPerformFunction<{
     onTrigger: {
@@ -165,7 +163,7 @@ export type FlowExecutionContextActions = FlowExecutionContext["components"];
  * 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, TDiscoveryState extends Record<string, unknown>> {
+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
@@ -177,7 +175,7 @@ interface BatchFields<TItem, TDiscoveryState extends Record<string, unknown>> {
      * (`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, TDiscoveryState>;
+    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. */
@@ -193,7 +191,7 @@ interface NonBatchFields {
  * The discriminated union coupling `batchConfig` and the batched `trigger`. Intersected
  * into each flow variant at {@link Flow}.
  */
-type BatchDiscriminant<TItem, TDiscoveryState extends Record<string, unknown>> = BatchFields<TItem, TDiscoveryState> | NonBatchFields;
+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, TItem = unknown> {
     /** The unique name for this flow. */
@@ -262,23 +260,23 @@ interface FlowBase<TTriggerPayload extends TriggerPayload = TriggerPayload, TIte
 }
 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, TItem = unknown, TDiscoveryState extends Record<string, unknown> = Record<string, unknown>> extends FlowBase<TTriggerPayload, TItem> {
+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, TDiscoveryState>;
+    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, TDiscoveryState>;
+    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, TItem = unknown, TDiscoveryState extends Record<string, unknown> = Record<string, unknown>> extends FlowBase<TTriggerPayload, TItem> {
+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.
@@ -296,10 +294,10 @@ interface PollingFlow<TInputs extends Inputs, TActionInputs extends Inputs, TPay
      * 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, TDiscoveryState>;
+    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, TItem = unknown, TDiscoveryState extends Record<string, unknown> = Record<string, unknown>> = (StandardFlow<TInputs, TPayload, TAllowsBranching, TResult, TTriggerPayload, TItem, TDiscoveryState> & BatchDiscriminant<TItem, TDiscoveryState>) | (PollingFlow<TInputs, TActionInputs, TPayload, TAllowsBranching, TResult, TTriggerPayload, TItem, TDiscoveryState> & BatchDiscriminant<TItem, TDiscoveryState>);
+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/TriggerDefinition.d.ts

@@ -14,15 +14,15 @@ import type { TriggerBaseResult, TriggerResult } from "./TriggerResult";
  * `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>> = {
+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, TDiscoveryState>;
+    triggerResolver?: TriggerResolverBehavior<TConfigVars, TPayload, TItem, TPaginationState>;
 } | {
     triggerResolverSupport: "required";
-    triggerResolver: TriggerResolverBehavior<TConfigVars, TPayload, TItem, TDiscoveryState>;
+    triggerResolver: TriggerResolverBehavior<TConfigVars, TPayload, TItem, TPaginationState>;
 };
 /**
  * Encodes the relationship between `onDeployPerform` and `onDeployResolver`. On-deploy is
@@ -34,12 +34,12 @@ export type TriggerResolverDecl<TConfigVars extends ConfigVarResultCollection, T
  * 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>> = {
+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, TDiscoveryState>;
+    onDeployResolver?: TriggerResolverBehavior<TConfigVars, TPayload, TItem, TPaginationState>;
 };
 declare const optionChoices: readonly ["invalid", "valid", "required"];
 export type TriggerOptionChoice = (typeof optionChoices)[number];
@@ -54,30 +54,30 @@ export declare const TriggerOptionChoices: TriggerOptionChoice[];
  *
  *   perform ──▶ resolveItems ──▶ [batch of TItem] ──▶ onExecution
  *                    │
- *                    └─ getNextDiscoveryState ──▶ payload.discoveryState ──▶ next perform
+ *                    └─ 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 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
+ * @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, TDiscoveryState extends Record<string, unknown> = Record<string, unknown>> {
+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<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;
+    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 `discoveryState` field narrowed to `TDiscoveryState`,
+ * 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 WithDiscoveryState<TPayload extends TriggerPayload, TDiscoveryState extends Record<string, unknown>> = Omit<TPayload, "discoveryState"> & {
-    discoveryState?: TDiscoveryState;
+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

package/dist/types/TriggerPayload.d.ts

@@ -5,11 +5,11 @@ 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.
  *
- * The optional `TDiscoveryState` parameter types the `discoveryState` field, so authors who
- * declare a pagination-state shape on their `getNextDiscoveryState` resolver can read back
+ * 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<TDiscoveryState extends Record<string, unknown> = 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;
@@ -56,7 +56,7 @@ export interface TriggerPayload<TDiscoveryState extends Record<string, unknown>
     /** 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.
+     *  Contains the object returned by `getNextPaginationState` from the previous round.
      *  Absent on the initial invocation. */
-    discoveryState?: TDiscoveryState;
+    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>, TDiscoveryState extends Record<string, unknown> = Record<string, unknown>> = (context: ActionContext<TConfigVars>, payload: TriggerPayload<TDiscoveryState>, 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.18.9-preview.1",
+  "version": "10.19.1-preview.0",
   "description": "Utility library for building Prismatic connectors and code-native integrations",
   "keywords": [
     "prismatic"