@zapier/kitcore 0.5.1 → 0.7.0

package/dist/index.d.mts

@@ -134,15 +134,17 @@ type ListPromptConfig = PromptConfig & {
 };
 /**
  * The prompt config the NEW-model resolvers (`defineResolver`) return. It omits
- * three fields the resolution controller does not honor, so authors can't
+ * four fields the resolution controller does not honor, so authors can't
  * supply a silent no-op:
- *  - `name`   — the framework supplies the answer key (always was overwritten).
- *  - `default`— no resolver uses it; the controller has no preselect concept.
- *  - `filter` — no resolver uses it; transform values in `listItems` instead.
- * (The legacy `SchemaParameterResolver` still honors `default`/`filter`, so the
- * full `PromptConfig` stays for that path.)
- */
-type ResolverPromptConfig = Omit<PromptConfig, "name" | "default" | "filter">;
+ *  - `name`    — the framework supplies the answer key (always was overwritten).
+ *  - `default` — no resolver uses it; the controller has no preselect concept.
+ *  - `filter`  — no resolver uses it; transform values in `listItems` instead.
+ *  - `validate`— validation is the resolver's top-level `validate`, which
+ *    never routes through rendering (and gets `imports`).
+ * (The legacy `SchemaParameterResolver` still honors `default`/`filter`/
+ * `validate`, so the full `PromptConfig` stays for that path.)
+ */
+type ResolverPromptConfig = Omit<PromptConfig, "name" | "default" | "filter" | "validate">;
 interface Resolver$1 {
     type: string;
     depends?: readonly string[] | string[];
@@ -571,11 +573,27 @@ interface DynamicResolver extends ResolverBase {
         cursor?: string;
     }) => ListItemsResult<unknown>;
     prompt?: (bag: {
+        /** The CURRENT page's items only — the engine windows the listing one
+         * page at a time (an accumulating host may be showing more). Rendering
+         * input only; validation is the top-level `validate`. */
         items: unknown[];
         input: Record<string, unknown>;
         /** The value `getContext` returned, if any. */
         context?: unknown;
     }) => ResolverPromptConfig;
+    /** Check a chosen/typed value before the engine accepts it. Async with
+     * `imports` so it can verify against the source (`tryResolveFromSearch`'s
+     * sibling for picks) — never against a loaded page: pagination means the
+     * pick can come from a page the engine no longer holds. Return true to
+     * accept or a message to re-ask with. A throw is a lookup failure (the
+     * host gets retry/cancel), not a rejection. */
+    validate?: (bag: {
+        imports: Record<string, unknown>;
+        value: unknown;
+        input: Record<string, unknown>;
+        /** The value `getContext` returned, if any. */
+        context?: unknown;
+    }) => Promise<true | string> | true | string;
     /** Resolve with no user input at all (e.g. a configured default), skipping the
      * prompt. Runs before prompting; used always in non-interactive mode and as a
      * "can we skip asking?" check otherwise. Returns null to fall through to a prompt. */
@@ -726,6 +744,11 @@ interface BoundDynamicResolver extends BoundResolverBase {
         input: Record<string, unknown>;
         context?: unknown;
     }) => ResolverPromptConfig;
+    validate?: (bag: {
+        value: unknown;
+        input: Record<string, unknown>;
+        context?: unknown;
+    }) => Promise<true | string> | true | string;
     tryResolveWithoutPrompt?: (bag: {
         input: Record<string, unknown>;
     }) => Promise<{
@@ -897,6 +920,21 @@ type StrictPage$1<TResponse> = SdkPage<unknown> & {
 type ItemOf$1<TResponse> = TResponse extends SdkPage<infer TItem> ? TItem : TResponse extends {
     data: readonly (infer TItem)[];
 } ? TItem : never;
+/**
+ * A response whose only own key is `data`. Gates the item overload of
+ * `defineMethod` the way `StrictPage` gates list-standard: `run` returns the
+ * `{ data }` envelope itself, and an envelope with extra keys is rejected (a
+ * future variant may accept metadata alongside `data`).
+ */
+type StrictItem<TResponse> = {
+    data: unknown;
+} & {
+    [K in Exclude<keyof TResponse, "data">]?: never;
+};
+/** Data type sourced from an item envelope. */
+type DataOf<TResponse> = TResponse extends {
+    data: infer TData;
+} ? TData : never;
 /**
  * A leaf plugin that is a single value (not a function). `value` is a static
  * constant; `get({ imports })` computes the value from imports. Like a
@@ -1928,8 +1966,8 @@ declare function createPluginStack<TRequires = object>(): PluginStack<TRequires,
  *
  * The `output` mode shapes `run`'s result into the public surface and drives
  * the overload that types the call: raw (default, passthrough), `item`
- * (`run` returns `T`, surfaced as `Promise<{ data: T }>`), or `list` (`run`
- * returns one `SdkPage`, surfaced as `PaginatedSdkResult`). See Output.
+ * (`run` returns `{ data: T }`, surfaced as `Promise<{ data: T }>`), or `list`
+ * (`run` returns one `SdkPage`, surfaced as `PaginatedSdkResult`). See Output.
  */
 declare function defineMethod<const TName extends string, TInput, TOutput, const TPositional extends readonly (keyof TInput & string)[] = readonly [], const TImports extends ImportsInput = readonly [], const TNamespace extends string = "", TState = undefined>(config: {
     name: TName;
@@ -1958,7 +1996,7 @@ declare function defineMethod<const TName extends string, TInput, TOutput, const
     }) => void | Promise<void>;
     run: (bag: MethodRunBag<ImportsOf<TImports>, TInput, TState>) => TOutput;
 } & LeafMetaFields): MethodPlugin<TName, TInput, TOutput, TPositional> & LeafSummary<TNamespace, TName, TImports>;
-declare function defineMethod<const TName extends string, TInput, TData, const TImports extends ImportsInput = readonly [], const TNamespace extends string = "", TState = undefined>(config: {
+declare function defineMethod<const TName extends string, TInput, TResponse extends StrictItem<TResponse>, TData = DataOf<TResponse>, const TImports extends ImportsInput = readonly [], const TNamespace extends string = "", TState = undefined>(config: {
     name: TName;
     namespace?: TNamespace;
     imports?: TImports & StaticList<TImports>;
@@ -1976,9 +2014,9 @@ declare function defineMethod<const TName extends string, TInput, TData, const T
         state: TState;
         input?: unknown;
     }) => void | Promise<void>;
-    run: (bag: MethodRunBag<ImportsOf<TImports>, TInput, TState>) => TData;
+    run: (bag: MethodRunBag<ImportsOf<TImports>, TInput, TState>) => TResponse | Promise<TResponse>;
 } & LeafMetaFields): MethodPlugin<TName, TInput, Promise<{
-    data: Awaited<TData>;
+    data: TData;
 }>> & LeafSummary<TNamespace, TName, TImports>;
 declare function defineMethod<const TName extends string, TInput, TResponse extends StrictPage$1<TResponse>, TItem = ItemOf$1<TResponse>, const TImports extends ImportsInput = readonly [], const TNamespace extends string = "", TState = undefined>(config: {
     name: TName;
@@ -2093,6 +2131,18 @@ declare function defineResolver<const TImports extends ImportsInput = readonly [
         /** The value `getContext` returned, if any. */
         context?: TContext;
     }) => ResolverPromptConfig;
+    /** Check a chosen/typed value before the engine accepts it. Async with
+     * `imports` so it can verify against the source — never against a loaded
+     * page (the pick can come from a page the engine no longer holds). Return
+     * true to accept or a message to re-ask with; a throw is a lookup failure
+     * (retry/cancel), not a rejection. */
+    validate?: (bag: {
+        imports: ImportsOf<TImports>;
+        value: unknown;
+        input: TInput;
+        /** The value `getContext` returned, if any. */
+        context?: TContext;
+    }) => Promise<true | string> | true | string;
     /** Resolve with no user input (e.g. a configured default), skipping the prompt. */
     tryResolveWithoutPrompt?: (bag: {
         imports: ImportsOf<TImports>;
@@ -2726,12 +2776,14 @@ interface ControllerAffordance {
 /** A question the host renders. Discriminated on `type`; the available moves are
  * the self-describing `actions` list (single source of truth, no flags).
  * `actions` is emitted in recommended presentation order — answer directly
- * (`choose`/`custom`/`add`), refine (`search`), paginate (`more`), decline
- * (`skip`/`done`), and failure questions offer `retry` then `cancel` — so a
- * minimal host can render the list verbatim, top to bottom. Hosts with richer
- * widgets (windowed lists, filter state) may reorder. */
+ * (`choose`/`custom`/`add`), refine (`search`), paginate
+ * (`next_page`/`previous_page`), decline (`skip`/`done`), and failure
+ * questions offer `retry` then `cancel` — so a minimal host can render the
+ * list verbatim, top to bottom. Hosts with richer widgets (windowed lists,
+ * filter state) may reorder. */
 type ControllerQuestion = {
     type: "select";
+    path: ControllerPath;
     message: string;
     /** What this field is, for an agent that lacks the schema. */
     description?: string;
@@ -2754,8 +2806,18 @@ type ControllerQuestion = {
      * in its lead-with-term prompt (e.g. "Enter or search app (e.g. 'slack')").
      * Only meaningful before a search has run. */
     placeholder?: string;
+    /** Where these `choices` sit in the paginated listing. `choices` is ONE
+     * page (payloads stay O(page); the engine never re-sends earlier pages).
+     * A window host renders the page and pages with
+     * `next_page`/`previous_page`; an accumulating host appends pages
+     * client-side: same `path` + same `generation` +
+     * advancing `index` means "extend what you showed", and a `generation`
+     * change (a search ran) means "start over". Absent on unpaginated
+     * selects (static enums). */
+    page?: ControllerSelectPage;
 } | {
     type: "input";
+    path: ControllerPath;
     message: string;
     description?: string;
     inputType: "text" | "password" | "email";
@@ -2763,6 +2825,7 @@ type ControllerQuestion = {
     actions: ControllerAffordance[];
 } | {
     type: "collection";
+    path: ControllerPath;
     message: string;
     description?: string;
     /** Which container kind this decision gates. `array` is the add-another
@@ -2791,6 +2854,15 @@ type ControllerQuestion = {
     max?: number;
     actions: ControllerAffordance[];
 };
+/** A select question's position in its paginated listing. */
+interface ControllerSelectPage {
+    /** Increments whenever the listing restarts (a `search` ran, even with the
+     * same term). An accumulating host discards what it has on a new
+     * generation. */
+    generation: number;
+    /** Zero-based page number within this generation. */
+    index: number;
+}
 /** The host's response to a question. The wire shape is frozen: a fuller
  * HATEOAS affordance schema would still produce exactly these. */
 type ControllerAction = {
@@ -2800,7 +2872,9 @@ type ControllerAction = {
     type: "search";
     term: string;
 } | {
-    type: "more";
+    type: "next_page";
+} | {
+    type: "previous_page";
 } | {
     type: "custom";
     value: string;
@@ -2821,7 +2895,7 @@ type ControllerAction = {
 type ControllerResult = {
     status: "ask";
     question: ControllerQuestion;
-    /** The prior answer's validation failure (`PromptConfig.validate`), when
+    /** The prior answer's validation failure (the resolver's `validate`), when
      * this is a re-ask. About the last transition, not the question itself. */
     error?: string;
 } | {
@@ -2874,9 +2948,10 @@ interface ControllerState {
      * add/done handling never infers the decision from value presence or
      * resolver shape. Absent when `current` is a plain leaf question. */
     gate?: "array" | "entry" | "optionals";
-    /** Listing progress for the current dynamic leaf (serializable: items +
-     * cursor, never a live iterator). */
-    listing?: ControllerListing;
+    /** Where pagination stands for the current dynamic leaf: coordinates only
+     * (cursor trail, generation), never items or live iterators — the page's
+     * items ride the ask's question. */
+    pagination?: ControllerPagination;
     /** Whether the host will prompt. Interactive (the default) always asks;
      * non-interactive runs `tryResolveWithoutPrompt` to auto-fill what it can
      * (e.g. configured defaults) before asking for the rest. */
@@ -2885,14 +2960,42 @@ interface ControllerState {
 /** A location in the input tree: top-level `["app"]`, a nested object field
  * `["inputs", "channel"]`, or (later) an array item `["records", 0, "id"]`. */
 type ControllerPath = (string | number)[];
-/** Accumulated candidate items for the current dynamic parameter, plus the
- * serializable cursor for "load more" and the active search term. */
-interface ControllerListing {
-    items: unknown[];
-    cursor?: string;
+/** Where a listing currently stands: the coordinates that make one page of a
+ * dynamic parameter's candidates fetchable — and re-fetchable — with no
+ * shared in-memory state. `previous_page` and `retry` work by re-issuing a
+ * recorded position. */
+interface ControllerListingPosition {
+    /** The active search term, when the resolver is search-mode. */
     search?: string;
-    /** True when the source reported no further pages. */
-    exhausted: boolean;
+    /** Cursor that fetched the current page; `null` is the first page. */
+    pageCursor: string | null;
+    /** Cursors of the pages before this one, oldest first (each entry fetches
+     * that page; `null` is the first page). `previous_page` pops the last. */
+    previousCursors: (string | null)[];
+    /** Increments on every listing restart (each `search`). Surfaced to hosts
+     * via {@link ControllerSelectPage} so accumulators know when to reset. */
+    generation: number;
+}
+/** The enumeration in progress for the current dynamic parameter:
+ * coordinates only. The fetched items ride the ask's `question.choices`; the
+ * host carries back these cursors between steps, never the items it was just
+ * shown. Anything the engine needs to redraw (a validate-rejection re-ask) it
+ * re-fetches statelessly from `position`. */
+interface ControllerPagination {
+    position: ControllerListingPosition;
+    /** Resume point for `next_page`; absent on the last page. */
+    nextCursor?: string;
+    /** The position whose fetch failed, kept so `retry` replays exactly it.
+     * Absent when the page loaded. */
+    retryPosition?: ControllerListingPosition;
+}
+/** One fetched page of a listing: the position it was fetched at plus what
+ * came back. Never stored: `toPagination` strips it to the coordinates the
+ * state keeps. */
+interface ControllerListingPage {
+    position: ControllerListingPosition;
+    items: unknown[];
+    nextCursor?: string;
 }
 /**
  * The one pluggable seam for the in-process `resolve` sugar. It receives the
@@ -3272,25 +3375,37 @@ interface PaginatedResult<TItem> {
     data: TItem[];
     nextCursor?: string;
 }
-type PaginatedSource<TItem> = () => PromiseLike<PaginatedResult<TItem>> & AsyncIterable<PaginatedResult<TItem>>;
 /**
- * Concatenate multiple paginated SDK results into a single paginated stream.
- * Each source is a function returning a dual Promise+AsyncIterable (as SDK
- * paginated methods return). Sources are drained in order.
+ * One page-at-a-time source for `concatPaginated`: called with that source's
+ * own cursor, resolves one page. An SDK paginated method fits directly
+ * (`({ cursor }) => sdk.listThings({ cursor })` — awaiting a paginated
+ * result yields the requested page).
+ */
+type PaginatedSource<TItem> = (options: {
+    cursor?: string;
+}) => PromiseLike<PaginatedResult<TItem>>;
+/**
+ * Concatenate multiple paginated sources into a single paginated stream.
+ * Sources are drained in order, one page per underlying call.
  *
- * The optional `dedupe` key extractor filters items from source N against
- * all items seen in sources 0 through N-1.
+ * Pagination is stateless: every outgoing cursor encodes which source to
+ * resume plus that source's own cursor, so a fresh `concatPaginated` call
+ * with `cursor` continues exactly where the previous page left off. Sources
+ * must therefore produce disjoint items themselves; there is no cross-source
+ * dedupe (an in-memory seen-set could not survive the cursor round-trip).
  *
  * Uses paginateBuffered internally to normalize page sizes across source
  * boundaries — e.g. if the first source only has 2 items, they'll be
  * buffered with items from the next source into a full page.
  *
- * Returns the same dual Promise+AsyncIterable shape that resolvers expect.
+ * The result is a thenable for the first page that also async-iterates
+ * pages in-process.
  */
-declare function concatPaginated<TItem>({ sources, dedupe, pageSize, }: {
+declare function concatPaginated<TItem>({ sources, pageSize, cursor, }: {
     sources: PaginatedSource<TItem>[];
-    dedupe?: (item: TItem) => string;
     pageSize?: number;
+    /** Cursor from a previous `concatPaginated` page; resumes the stream. */
+    cursor?: string;
 }): PromiseLike<PaginatedResult<TItem>> & AsyncIterable<PaginatedResult<TItem>>;
 /**
  * Strip the PromiseLike from an async iterable, returning a plain
@@ -3380,4 +3495,4 @@ declare class CoreCancelledSignal extends CoreSignal {
     constructor(message?: string);
 }
 
-export { type AdaptError, type AdaptErrorOptions, type AdaptPage, type AggregatePlugin, type ArrayResolver$1 as ArrayResolver, type AsyncContext, type BoundFormatter, type BoundResolver, CONTEXT, CORE_ERROR_SYMBOL, CORE_OPTIONS_ID, CORE_SIGNAL_SYMBOL, type CategoryDefinition, type ConstantResolver$1 as ConstantResolver, type Controller, type ControllerAction, type ControllerAffordance, type ControllerAnswerFn, type ControllerChoice, type ControllerError, type ControllerIssue, type ControllerListing, type ControllerMethodDescription, type ControllerMethodSummary, type ControllerParameterDescription, type ControllerPath, type ControllerQuestion, type ControllerResult, type ControllerSdk, type ControllerState, type CoreApiError, CoreCancelledSignal, CoreDisposeError, CoreError, CoreErrorCode, type CoreErrorOptions, type CoreOptions, CoreSignal, type CreateSdkOptions, type DeprecatedPromptConfigChoice, type DeprecationLogger, type DeprecationWarning, type DisposeFn, type DynamicListResolver, type DynamicMember, type DynamicResolver$1 as DynamicResolver, type DynamicSearchResolver, type FieldsResolver, type FormattedItem, type Formatter, type FunctionDeprecation, type FunctionRegistryEntry, type HookPlugin, type LeafMeta, type LeafSummary, type LegacyMergePlugin, type LegacyPlugin, type ListItemsResult, type ListPromptConfig, type MethodAttachment, type MethodHooks, type MethodOverridePlugin, type MethodPlugin, type MethodScope, type Resolver as ModelResolver, type OnMethodEnd, type OnMethodEndContext, type OnMethodStart, type OnMethodStartContext, type OutputFormatter, type PaginatedSdkFunction, type PaginatedSdkResult, type Plugin, type PluginMeta, type PluginProvides, type PluginStack, type PluginSummary, type PluginSurface, type PositionalMetadata, type PromptConfig, type PromptConfigChoice, type PropertyPlugin, type RegistryResult, type RequiredSdkOf, type Resolver$1 as Resolver, type ResolverConfig, type ResolverFieldItem, type ResolverMetadata, type ResolverPromptConfig, type ResolverType, type Sdk, type SdkContext, type SdkPage, type StaticResolver$1 as StaticResolver, type ValidResolvers, addPlugin, composePlugins, concatPaginated, coreOptionsPluginRef, createAsyncContext, createController, createCoreError, createCorePlugin, createDeprecationLogger, createFunction, createPaginatedFunction, createPaginatedPluginMethod, createPluginMethod, createPluginStack, createPrefixedCursor, createSdk, createValidator, dangerousContextPlugin, declareMethod, declareOptionalProperty, declarePlugin, declareProperty, decodeIncomingCursor, defaultLogDeprecation, defineFormatter, defineHook, defineLegacyMerge, defineMethod, defineMethodOverride, definePlugin, defineProperty, defineResolver, disposeSdk, fromFunctionPlugin, getContext, getCoreErrorCause, getCoreErrorCode, getCurrentDepth, getCurrentScope, getFieldDescriptions, getOutputSchema, getRegistryPlugin, getSchemaDescription, isCoreError, isCoreSignal, isNestedMethodCall, isPositional, isTelemetryNested, omitExports, openEnum, paginate, paginateBuffered, paginateMaxItems, resolvePlugin, runInMethodScope, runWithTelemetryContext, selectExports, splitPrefixedCursor, toIterable, toSnakeCase, toTitleCase, validateOptions, withOutputSchema, withPositional, withResolver };
+export { type AdaptError, type AdaptErrorOptions, type AdaptPage, type AggregatePlugin, type ArrayResolver$1 as ArrayResolver, type AsyncContext, type BoundFormatter, type BoundResolver, CONTEXT, CORE_ERROR_SYMBOL, CORE_OPTIONS_ID, CORE_SIGNAL_SYMBOL, type CategoryDefinition, type ConstantResolver$1 as ConstantResolver, type Controller, type ControllerAction, type ControllerAffordance, type ControllerAnswerFn, type ControllerChoice, type ControllerError, type ControllerIssue, type ControllerListingPage, type ControllerListingPosition, type ControllerMethodDescription, type ControllerMethodSummary, type ControllerPagination, type ControllerParameterDescription, type ControllerPath, type ControllerQuestion, type ControllerResult, type ControllerSdk, type ControllerSelectPage, type ControllerState, type CoreApiError, CoreCancelledSignal, CoreDisposeError, CoreError, CoreErrorCode, type CoreErrorOptions, type CoreOptions, CoreSignal, type CreateSdkOptions, type DeprecatedPromptConfigChoice, type DeprecationLogger, type DeprecationWarning, type DisposeFn, type DynamicListResolver, type DynamicMember, type DynamicResolver$1 as DynamicResolver, type DynamicSearchResolver, type FieldsResolver, type FormattedItem, type Formatter, type FunctionDeprecation, type FunctionRegistryEntry, type HookPlugin, type LeafMeta, type LeafSummary, type LegacyMergePlugin, type LegacyPlugin, type ListItemsResult, type ListPromptConfig, type MethodAttachment, type MethodHooks, type MethodOverridePlugin, type MethodPlugin, type MethodScope, type Resolver as ModelResolver, type OnMethodEnd, type OnMethodEndContext, type OnMethodStart, type OnMethodStartContext, type OutputFormatter, type PaginatedSdkFunction, type PaginatedSdkResult, type Plugin, type PluginMeta, type PluginProvides, type PluginStack, type PluginSummary, type PluginSurface, type PositionalMetadata, type PromptConfig, type PromptConfigChoice, type PropertyPlugin, type RegistryResult, type RequiredSdkOf, type Resolver$1 as Resolver, type ResolverConfig, type ResolverFieldItem, type ResolverMetadata, type ResolverPromptConfig, type ResolverType, type Sdk, type SdkContext, type SdkPage, type StaticResolver$1 as StaticResolver, type ValidResolvers, addPlugin, composePlugins, concatPaginated, coreOptionsPluginRef, createAsyncContext, createController, createCoreError, createCorePlugin, createDeprecationLogger, createFunction, createPaginatedFunction, createPaginatedPluginMethod, createPluginMethod, createPluginStack, createPrefixedCursor, createSdk, createValidator, dangerousContextPlugin, declareMethod, declareOptionalProperty, declarePlugin, declareProperty, decodeIncomingCursor, defaultLogDeprecation, defineFormatter, defineHook, defineLegacyMerge, defineMethod, defineMethodOverride, definePlugin, defineProperty, defineResolver, disposeSdk, fromFunctionPlugin, getContext, getCoreErrorCause, getCoreErrorCode, getCurrentDepth, getCurrentScope, getFieldDescriptions, getOutputSchema, getRegistryPlugin, getSchemaDescription, isCoreError, isCoreSignal, isNestedMethodCall, isPositional, isTelemetryNested, omitExports, openEnum, paginate, paginateBuffered, paginateMaxItems, resolvePlugin, runInMethodScope, runWithTelemetryContext, selectExports, splitPrefixedCursor, toIterable, toSnakeCase, toTitleCase, validateOptions, withOutputSchema, withPositional, withResolver };