@prismatic-io/spectral 10.18.7 → 10.18.9-preview.0

package/dist/types/IntegrationDefinition.d.ts

@@ -4,13 +4,15 @@ 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, WithDiscoveryState } from "./TriggerDefinition";
 import type { TriggerEventFunction } from "./TriggerEventFunction";
 import type { TriggerPayload } from "./TriggerPayload";
 import type { TriggerPerformFunction } from "./TriggerPerformFunction";
-import type { TriggerResult } from "./TriggerResult";
+import type { TriggerBaseResult, TriggerResult } from "./TriggerResult";
 /**
  * Defines attributes of a code-native integration. See
  * https://prismatic.io/docs/integrations/code-native/
@@ -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`/`TDiscoveryState`/`TTriggerPayload` let flows with
+     * different resolver item and cursor types live in one array. `integration` only holds
+     * and serializes these flows (it never invokes `onExecution`), so the precise — and
+     * per-flow distinct — `onExecution` param type does not need to be preserved here.
      */
-    flows: Flow<TInputs, TActionInputs, TPayload, TAllowsBranching, TResult>[];
+    flows: Flow<TInputs, TActionInputs, TPayload, TAllowsBranching, TResult, any, any, any>[];
     /**
      * Config wizard pages for this integration. See
      * https://prismatic.io/docs/integrations/code-native/config-wizard/
@@ -70,12 +77,66 @@ 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 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.
+ */
+export interface BatchedTriggerReturn<TItem> {
+    /** The records produced by this trigger fire. Chunked into batches of the flow's `batchConfig.batchSize`. */
+    items: TItem[];
+    /** 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.
+ */
+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`.
+     */
+    onTrigger: (context: ActionContext<ConfigVars>, payload: TriggerPayload<TPaginationState>) => Promise<BatchedTriggerReturn<TItem>>;
+    /**
+     * The on-deploy trigger fire, run once on initial instance deploy. Same shape as `onTrigger`;
+     * pair with `getNextOnDeployPaginationState` to paginate.
+     */
+    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>;
+}
+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 +146,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, TDiscoveryState 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, TDiscoveryState>;
+    /** 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, TDiscoveryState extends Record<string, unknown>> = BatchFields<TItem, TDiscoveryState> | 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 +252,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, TDiscoveryState 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, TDiscoveryState>;
+    /**
+     * Function to execute on initial instance deploy, in addition to (and independent of) `onTrigger`.
+     * Typically used to backfill baseline records for systems whose webhooks only emit future events.
+     */
+    onDeployTrigger?: TriggerPerformFunction<TInputs, ConfigVars, TAllowsBranching, TResult, TDiscoveryState>;
 }
 export type PollingTriggerType = "polling";
 /** A polling flow that runs on a schedule and has access to polling context (getState/setState). */
-interface PollingFlow<TInputs extends Inputs, TActionInputs extends Inputs, TPayload extends TriggerPayload = TriggerPayload, TAllowsBranching extends boolean = boolean, TResult extends TriggerResult<TAllowsBranching, TPayload> = TriggerResult<TAllowsBranching, TPayload>, TTriggerPayload extends TriggerPayload = TriggerPayload> extends FlowBase<TTriggerPayload> {
+interface PollingFlow<TInputs extends Inputs, TActionInputs extends Inputs, TPayload extends TriggerPayload = TriggerPayload, TAllowsBranching extends boolean = boolean, TResult extends TriggerResult<TAllowsBranching, TPayload> = TriggerResult<TAllowsBranching, TPayload>, TTriggerPayload extends TriggerPayload = TriggerPayload, TItem = unknown, TDiscoveryState extends Record<string, unknown> = Record<string, unknown>> extends FlowBase<TTriggerPayload, TItem> {
     /**
      * 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 +292,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, TDiscoveryState>;
 }
 /** Defines attributes of a flow of a code-native integration. */
-export type Flow<TInputs extends Inputs, TActionInputs extends Inputs, TPayload extends TriggerPayload = TriggerPayload, TAllowsBranching extends boolean = boolean, TResult extends TriggerResult<TAllowsBranching, TPayload> = TriggerResult<TAllowsBranching, TPayload>, TTriggerPayload extends TriggerPayload = TriggerPayload> = StandardFlow<TInputs, TPayload, TAllowsBranching, TResult, TTriggerPayload> | PollingFlow<TInputs, TActionInputs, TPayload, TAllowsBranching, TResult, TTriggerPayload>;
+export type Flow<TInputs extends Inputs, TActionInputs extends Inputs, TPayload extends TriggerPayload = TriggerPayload, TAllowsBranching extends boolean = boolean, TResult extends TriggerResult<TAllowsBranching, TPayload> = TriggerResult<TAllowsBranching, TPayload>, TTriggerPayload extends TriggerPayload = TriggerPayload, TItem = unknown, TDiscoveryState extends Record<string, unknown> = Record<string, unknown>> = (StandardFlow<TInputs, TPayload, TAllowsBranching, TResult, TTriggerPayload, TItem, TDiscoveryState> & BatchDiscriminant<TItem, TDiscoveryState>) | (PollingFlow<TInputs, TActionInputs, TPayload, TAllowsBranching, TResult, TTriggerPayload, TItem, TDiscoveryState> & BatchDiscriminant<TItem, TDiscoveryState>);
 export type FlowTriggerType = PollingTriggerType | StandardTriggerType;
 /** Defines attributes of a Preprocess flow Configuration used by a flow of an integration. */
 export type PreprocessFlowConfig = {

package/dist/types/PollingTriggerDefinition.d.ts

@@ -4,6 +4,7 @@ import type { ActionContext } from "./ActionPerformFunction";
 import type { ActionPerformReturn } from "./ActionPerformReturn";
 import type { ActionDisplayDefinition } from "./DisplayDefinition";
 import type { ConfigVarResultCollection, Inputs } from "./Inputs";
+import type { BatchConfig, OnDeployDecl, TriggerResolverDecl } from "./TriggerDefinition";
 import type { TriggerEventFunction } from "./TriggerEventFunction";
 import type { TriggerPayload } from "./TriggerPayload";
 import type { TriggerResult } from "./TriggerResult";
@@ -18,11 +19,21 @@ export type PollingTriggerPerformFunction<TInputs extends Inputs, TActionInputs
 /**
  * PollingTriggerDefinition is the type of the object that is passed in to `pollingTrigger` function to
  * define a component trigger.
+ *
+ * Composed from `PollingTriggerDefinitionBase` plus `TriggerResolverDecl` (resolver support)
+ * and `OnDeployDecl` (the on-deploy perform/resolver relationship), enforced at the type level.
  */
-export interface PollingTriggerDefinition<TInputs extends Inputs = Inputs, TConfigVars extends ConfigVarResultCollection = ConfigVarResultCollection, TPayload extends TriggerPayload = TriggerPayload, TAllowsBranching extends boolean = boolean, TResult extends TriggerResult<TAllowsBranching, TPayload> = TriggerResult<TAllowsBranching, TPayload>, TActionInputs extends Inputs = Inputs, TAction extends ActionDefinition<TActionInputs> = ActionDefinition<TActionInputs>, TCombinedInputs extends TInputs & TActionInputs = TInputs & TActionInputs> {
+export type PollingTriggerDefinition<TInputs extends Inputs = Inputs, TConfigVars extends ConfigVarResultCollection = ConfigVarResultCollection, TPayload extends TriggerPayload = TriggerPayload, TAllowsBranching extends boolean = boolean, TResult extends TriggerResult<TAllowsBranching, TPayload> = TriggerResult<TAllowsBranching, TPayload>, TActionInputs extends Inputs = Inputs, TAction extends ActionDefinition<TActionInputs> = ActionDefinition<TActionInputs>, TCombinedInputs extends TInputs & TActionInputs = TInputs & TActionInputs> = PollingTriggerDefinitionBase<TInputs, TConfigVars, TPayload, TAllowsBranching, TResult, TActionInputs, TAction, TCombinedInputs> & TriggerResolverDecl<TConfigVars, TPayload> & OnDeployDecl<TInputs, TConfigVars, TPayload, TAllowsBranching, TResult>;
+interface PollingTriggerDefinitionBase<TInputs extends Inputs = Inputs, TConfigVars extends ConfigVarResultCollection = ConfigVarResultCollection, TPayload extends TriggerPayload = TriggerPayload, TAllowsBranching extends boolean = boolean, TResult extends TriggerResult<TAllowsBranching, TPayload> = TriggerResult<TAllowsBranching, TPayload>, TActionInputs extends Inputs = Inputs, TAction extends ActionDefinition<TActionInputs> = ActionDefinition<TActionInputs>, TCombinedInputs extends TInputs & TActionInputs = TInputs & TActionInputs> {
     triggerType?: "polling";
     /** Defines how the Action is displayed in the Prismatic interface. */
     display: ActionDisplayDefinition;
+    /**
+     * Default batch-dispatch config shared by `triggerResolver` and `onDeployResolver`.
+     * Required when this trigger declares either (a `triggerResolver` with
+     * `triggerResolverSupport` `"valid"`/`"required"`, or an `onDeployResolver`).
+     */
+    batchConfig?: BatchConfig;
     /** Defines your trigger's polling behavior. */
     pollAction?: TAction;
     /** Function to perform when this Trigger is invoked. A default perform will be provided for most polling triggers but defining this allows for custom behavior. */
@@ -39,3 +50,4 @@ export interface PollingTriggerDefinition<TInputs extends Inputs = Inputs, TConf
     examplePayload?: Awaited<ReturnType<this["perform"]>>;
 }
 export declare const isPollingTriggerDefinition: (ref: unknown) => ref is PollingTriggerDefinition;
+export {};

package/dist/types/TriggerDefinition.d.ts

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

package/dist/types/TriggerPayload.d.ts

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

package/dist/types/TriggerPerformFunction.d.ts

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prismatic-io/spectral",
-  "version": "10.18.7",
+  "version": "10.18.9-preview.0",
   "description": "Utility library for building Prismatic connectors and code-native integrations",
   "keywords": [
     "prismatic"
@@ -44,8 +44,8 @@
   "dependencies": {
     "axios": "^1.16.1",
     "axios-retry": "^4.5.0",
-    "date-fns": "^4.1.0",
-    "ejs": "^5.0.2",
+    "date-fns": "^4.4.0",
+    "ejs": "^6.0.1",
     "form-data": "^4.0.5",
     "fs-extra": "^11.3.5",
     "jest-mock": "^30.4.1",
@@ -62,14 +62,14 @@
     "@types/ejs": "3.1.5",
     "@types/fs-extra": "11.0.4",
     "@types/lodash": "^4.17.24",
-    "@types/node": "^25.7.0",
+    "@types/node": "^25.9.1",
     "@types/prettier": "^3.0.0",
     "@types/sax": "^1.2.7",
     "@types/valid-url": "^1.0.7",
-    "@vitest/ui": "^4.1.6",
+    "@vitest/ui": "^4.1.8",
     "copyfiles": "2.4.1",
     "fast-check": "^4.8.0",
     "typescript": "6.0.3",
-    "vitest": "^4.1.6"
+    "vitest": "^4.1.8"
   }
 }